For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from hours to days) learning these.
Operating system administration: Ability to use Unix/Linux command line tools (or equivalent Windows tools), including ability to move/copy/delete files, change permissions, view web server log files, set environment variables, use a text editor, etc.
Web server administration: Ability to do basic setup, e.g. ability to edit config files or use GUI configuration tools to enable CGI scripts on a directory.
Program compilation:Where RCS is not pre-installed (that is most Unix systems), the ability to download and compile the RCS program from source, including use of configure, make, etc. This is often not necessary on Linux or Windows.
Troubleshooting: Ability to perform tests, inspect error logs, talk to technical support (whether in an IT department or web hosting provider) and read documentation in order to help with diagnosing installation problems.
Installing TWiki is not recommended for people who only know HTML and web design, unless they are willing to learn the above, or team up with someone who can handle the installation.
Although the TWikiInstallationGuide is quite complete, there will on occasion be parts that don't work in your local environment (particularly with TWiki:Codev/TWikiOnWebHostingSites, which are sometimes challenging even for those with good OS and web server skills).
There are many excellent resources for learning how to administer your OS and web server, including books, web sites, web forums, IM and email lists. The TWiki:Support web must not be depended on as a resource for this purpose - in other words, it is not there to answer basic questions about operating system and web server administration. Asking and answering questions is time consuming for all concerned and is best used for specific TWiki related issues, rather than helping you learn the OS and web server.
-- RichardDonkin - 27 Apr 2002
-- GrantBow - 15 Jan 2003
Annotated directory and file listings, for the 01-Feb-2003 TWiki production release.
Who and What is This Good For?
Interested Users and Site Administrators can find out in simple terms what each part of TWiki actually does. Adventurous Adminstrators with server access to files (via telnet, ssh or ftp) can also figure out where to look to make minor modifications, like changing hardcode text or color. Software Developers can get an at-a-glance overview of TWiki code architecture.
Directory Structure
You can rename the root TWiki directory - twiki - to whatever you like by changing it in the TWiki.cfg configuration file. However, to keep the current installation and future upgrades simple, you should leave the five main subdirectories intact:
Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Store/RcsFile.pm
Generic file handling code, a class
TWiki/Store/RcsWrap.pm
Wrappers around RCS executables, a class that inherits from RcsFile
TWiki/Store/RcsLite.pm
A Perl RCS implemention, a class that inherits from RcsFile
TWiki/Plugins/DefaultPlugin.pm
Handles some legacy rules
TWiki/Plugins/EmptyPlugin.pm
Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm
Use aliases as links for predefined URLs
Files under twiki/pub
The pub directory stores topic-related files, including images used by TWiki and FileAttachments. Attachments are stored in subdirectories created with the related topic name. You can also upload files directly for and link manually (but not through Attach) Partial file list:
Lookup table to translate file extension to file type
icn/bat.gif
GIF file for file type
icn/bmp.gif
GIF file for file type
...
...
TWiki/FileAttachment/Sample.txt
TEXT file: sample
TWiki/FileAttachment/Smile.gif
GIF image: sample
TWiki/FileAttachment/Smile.gif,v
RCS repository for GIF file
TWiki/PreviewBackground/blankltgraybg.gif
GIF image
TWiki/PreviewBackground/blankwhitebg.gif
GIF image
TWiki/PreviewBackground/previewbg.gif
GIF image: Preview view background
TWiki/PreviewBackground/preview2bg.gif
GIF image: Alternate preview view background
TWiki/TWikiLogos/twikiRobot121x54.gif
GIF image: TWiki logo
...
...
TWiki/TWikiTemplates/testscreen.gif
GIF image: Screen shot
TWiki/WabiSabi/wabisabi.gif
GIF image: illustration
Know/IncorrectDllVersionW32PTH10DLL/W32PTH10.DLL
DLL file: sample
Files under twiki/data
TWiki topics: data stored as individual text files and rendered by TWiki for display as regular Web pages. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - Main, TWiki, Know, Sandbox - with documentation and demo content, a Trash web for browser-based, recoverable topic deletion, and a _default directory containing a core topic set required to start a new web. Partial file list:
Rename/move control screen (choose web & new topic tile
renamebase.tmpl
Used by other rename templates
renameconfirm.tmpl
Confirms a pre-specified rename, ex: undoing a rename
renamerefs.tmpl
Display if rename done, but some references not changed (topics were locked)
search.tmpl
Search screen
searchbookview.tmpl
Search results with full topic content
searchformat.tmpl
Search screen for formatted search
searchmeta.tmpl
Search screen
searchrenameview.tmpl
Used by rename to list references to topic being renamed
twiki.tmpl
Master template: definitions are used by other templates
view.plain.tmpl
Skin for bare bone topic view without header/footer
view.print.tmpl
Skin for printable topic view with a simple header/footer
view.rss.tmpl
Skin for topic view in RDF XML format
view.tmpl
Main topic view - the standard regular Web page
TWiki File System Snapshot
The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.
On an ISP installation... The user and group - twiki twiki - will probably be your domain or login name, eg: yourdomain yourdomain and can't be changed; same for nobody nobody files further down. Also, in the bin directory, scripts might need a .cgi (sometimes .pl) extension._
Directory twiki/bin:
drwxrwxr-x 2 twiki twiki 4096 Jan 7 23:56 .
drwxrwxr-x 5 twiki twiki 4096 Nov 18 12:21 ..
-rw-rw-r-- 1 twiki twiki 979 Aug 3 19:36 .htaccess
-rw-rw-r-- 1 twiki twiki 1598 Jun 1 2002 .htaccess.txt
-rwxrwxr-x 1 twiki twiki 4986 Jan 4 17:27 attach
-rwxrwxr-x 1 twiki twiki 3734 Jan 4 17:27 changes
-rwxrwxr-x 1 twiki twiki 9362 Jan 4 18:04 edit
-rwxrwxr-x 1 twiki twiki 1878 Jan 4 17:28 geturl
-rwxrwxr-x 1 twiki twiki 4587 Jan 4 17:28 installpasswd
-rwxrwxr-x 1 twiki twiki 7231 Jan 6 09:04 mailnotify
-rwxrwxr-x 1 twiki twiki 6000 Dec 11 01:26 makedistrib
-rwxrwxr-x 1 twiki twiki 8228 Jan 4 18:25 manage
-rwxrwxr-x 1 twiki twiki 2445 Jan 4 18:08 oops
-rwxrwxr-x 1 twiki twiki 6936 Jan 4 18:08 passwd
-rwxrwxr-x 1 twiki twiki 5820 Jan 4 17:30 preview
-rwxrwxr-x 1 twiki twiki 9235 Jan 4 17:31 rdiff
-rwxrwxr-x 1 twiki twiki 10584 Jan 4 18:09 register
-rwxrwxr-x 1 twiki twiki 14746 Jan 5 00:14 rename
-rwxrwxr-x 1 twiki twiki 4800 Jan 4 18:09 save
-rwxrwxr-x 1 twiki twiki 4729 Jan 4 17:32 search
-rw-rw-r-- 1 twiki twiki 1446 Jan 8 01:03 setlib.cfg
-rwxrwxr-x 1 twiki twiki 19261 Jan 4 17:33 statistics
-rwxrwxr-x 1 twiki twiki 30626 Jan 4 17:33 testenv
-rwxrwxr-x 1 twiki twiki 14306 Jan 4 18:11 upload
-rwxrwxr-x 1 twiki twiki 11414 Jan 5 01:12 view
-rwxrwxr-x 1 twiki twiki 2944 Jan 5 00:36 viewfile
BookView is an option available from the WebSearch topic. It allows you to display the result in "book view", that is, the whole content of topics is shown instead of a topic summary. This allows you to easily see a whole set of pages, which is useful for printing.
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
If you have questions please contact the TWiki webmaster caad-yearly@hbt.arch.ethz.ch.
The default plugin is used for some deprecated rendering of older TWiki versions and of JosWiki. This plugin can also be used to specify some simple custom rendering rules. Note: Create a new TWikiPlugin based on EmptyPlugin if you plan to offer some complex rendering or other functionality.
Syntax Rules
Custom rendering rules of the default plugin:
Allow old include syntax ( %INCLUDE:"TopicName"% ) if Plugin Preferences variable OLDINCLUDE is set to 1
Render deprecated *_text_* as bold italic text. Test if installed: This is bold italic
Enable JosWiki rules if JosWiki specific code is uncommented
Modify file TWiki/Plugins/DefaultPlugin.pm to add your own rules or to enable JosWiki rules.
DefaultPlugin Settings
Plugin settings are stored as preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, for example, %DEFAULTPLUGIN_SHORTDESCRIPTION%
New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously, these operations could only be done manually, by someone with file-level access to the Web server).
Moving lets you transfer a topic from one web to another. The soft delete moves a topic to the special Trash web, where it's hidden but can be "undeleted" with system administrator access.
Click [More] on the control bar at the bottom of the page you want to change, then choose [Rename/move], and make your changes that screen. There's a link that launches to the ManagingTopics reference page in a pop-up window.
NOTE: The configuration of your site and your own access permissions determine whether you can access these functions.
Back to:TWikiFAQ
-- MikeMannix - 14 Sep 2001
Use the "Minor changes, don't notify" checkbox in preview in case you only make a minor change to a topic and you do not want to inform everybody who is on the WebNotify list of the current web of this change.
Note: No new revision is created in case you save the same topic again within a certain time frame (default is one hour). You only need to checkmark the "Minor change, don't notify" checkbox once within this time frame, because subsequent save operations do not notify users.
Note: The initial state of the checkbox can be set to on with the DONTNOTIFYCHECKBOX preferences variable. See TWikiPreferences for more.
Why does the topic revision not increase when I edit a topic?
Answer:
The same topic revision will be used when you save a topic again within a certain time frame (one hour by default). This is to prevent unnecessary topic revisions when you do several edit cycles in a row. Note that a new revision is created if another person edits the same topic, regardless of the time.
Back to:TWikiFAQ
-- PeterThoeny - 27 Nov 2000
This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an [ Edit table ] button if preceeded by an %EDITTABLE{...}% variable. Each column can be a text field, a drop down box, a date field, etc. Multiple tables per topic are editable, but only one at a time can be edited.
Add a %EDITTABLE{...}% variable just before an existing table to make it editable, or add the variable anywhere in a topic to start a new table. Parameters:
Specify the header format of a new table like "|*Food*|*Drink*|". Useful to start a table with only a button
(no header)
format
The format of one column when editing the table. A cell can be a text input field, or any of these edit field types: • Text input field (1 line): | text, <size>, <initial value> | • Textarea input field: | textarea, <rows>x<columns>, <initial value> | • Drop down box: | select, <size>, <option 1>, <option 2>, etc | • Radio buttons: | radio, <size*>, <option 1>, <option 2>, etc | * size indicates the number of buttons per line in edit mode • Checkboxes: | checkbox, <size*>, <option 1>, <option 2>, etc | * size indicates the number of checkboxes per line in edit mode • Fixed label: | label, 0, <label text> | • Row number: | row, <offset> | • Date: | date, <size>, <initial value>, <DHTML date format> |
"text, 16" for all cells
changerows
Rows can be added and removed if "on"; Rows can be added but not removed if "add"
CHANGEROWS Plugin setting
quietsave
Quiet Save button is shown if "on", hidden if "off"
QUIETSAVE Plugin setting
include
Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place.
(none)
helptopic
Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% variables can be used in the topic to specify what is shown.
(no help text)
headerislabel
Table header cells are read-only (labels) if "on"; header cells can be edited if "off" or "0"
"on"
editbutton
Set edit button text, e.g. "Edit this table"; set button image with alt text, e.g. "Edit table, %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/edittopic.gif"; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell)
EDITBUTTON Plugin setting
Initial Values
By default, variables in <initial value> (of text input field) and <label text> (of fixed label) get expanded when a new row is added. This can be used for example to add a timestamp to a label. You can escape characters if you do not want that:
Double quote ("). Alternatively write \" to escape it
$percnt
Percent sign (%)
$dollar
Dollar sign ($)
$nop or $nop()
Is a "no operation"
Date Field Type
The date field type allows one to choose a date with a popup calendar. Popup calendar works for Netscape 6.0 or better, all other Gecko-based browsers, Internet Explorer 5.0 or better for Windows, Opera 7 and Konqueror 3.1.2. The ... button is inactive if the browser cannot support the popup calendar. It uses the nice Mishoo DHTML calendar, see also TWiki:Codev/JavaScriptDatePickerForForm
Per Cell Settings
An individual edit field type can be defined for each table cell. Place an %EDITCELL{ "type, ..." }% variable at the end of the cell content. This is useful to override the per column %EDITTABLE{ format="..." }% settings, or to create tables with key/value rows. All edit field types of the format="..." parameter are supported. For example, to define a text field, type: | cell content %EDITCELL{ "text, 20" }% |
It is also possible to place the edit button inside a cell instead of default location below the table. Type | %EDITCELL{ "editbutton, 1, Edit this table" }% | to show a button, or | %EDITCELL{ "editbutton, 1, Edit table, Image-URL" }% | to show a button image with alternate text.
Note: The %EDITCELL{ }%=variable cannot be used by itself; place an =%EDITTABLE{ }%=variable at the beginning of a table where you want to use =%EDITCELL{ }% variables.
Table Buttons
Examples
Line before table: %EDITTABLE{ format="| row, -1 | text, 20, init | select, 1, one, two, three, four | radio, 3,:-),:-I,:-( | label, 0, %SERVERTIME{"$day $mon $year $hour:$min"}% |" changerows="on" }%Note: Please do not save this example table! Use TWiki:Sandbox.EditTablePluginTesting if you want to try out this Plugin
If this plugin is installed you will see an [ Edit table ] button above; if you were to click on it (please don't, use TWiki:Sandbox.EditTablePluginTesting for testing) you get this form:
The following example shows a simple table with key/value rows. The default edit field type for the value column is a text field. This is overloaded by a selector for the Gender, and a date picker for the DOB. This is typically used by TWiki applications where new topics with tables are created based on a template topic.
You type:
%EDITTABLE{ format="| label | text, 40 |" }%
|*Key*|*Value*|
| Name: | John Smith |
| Gender: | M %EDITCELL{select, 1, , F, M}% |
| DOB: | 1999/12/31 %EDITCELL{date, 10}% |
| City: | New York |
Screenshot:
Screenshot in edit mode:
Plugin Settings
Plugin settings are stored as preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, for example, %EDITTABLEPLUGIN_SHORTDESCRIPTION%
Language of DHTML calendar, pointing to attached calendar-<code>.js language file: en, af, br, ca, cs-win, da, de, du, el, es, fr, hr, hr-utf8, hu, it, jp, nl, no, pl, pt, ro, ru, sk, sp, sv, tr, zh
Set JSCALENDARLANGUAGE = en
Additional options of DHTML calendar:
Set JSCALENDAROPTIONS =
Note: The Plugin looks for the JSCALENDAR* settings first in the TWiki Preferences, then in above Plugin settings
Limitations and Known Issues
This Plugin does not support TWiki table formatting like Multi-span cells (e.g. | ... ||) and cell justification (e.g. | centered | right |)
There is a performance issue when editing a large table, say, with more then 50 rows
Variables like %ATTACHURL% get expanded unless they are in a label
You cannot put two %EDITTABLE{}% statements on the same line in the source
You can include %-vars now in select values, by quoting them with <nop>, as in %<nop>X% for %X%, say for instance:
select,1,%<nop>X%,%<nop>Y%
Plugin Installation Instructions
Note: You do not need to install anything on the browser to use this Plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
Download the ZIP file from the Plugin web (see below)
Unzip EditTablePlugin.zip in your twiki installation directory. Content:
The Plugin depends on the viewauth script to authenticate the user. As described in TWikiAccessControl, copy the view script to viewauth (or better, create a symbolic link) and add viewauth to the list of authenticated scripts in the .htaccess file.
The Mishoo DHTML calendar 0.9.5 is preinstalled and should work without any configuration. If you wish to use another language, specify the in the Plugin settings, or create a new language files, attach it to the Plugin topic, and change the Plugin settings
Test if the Plugin is correctly installed:
Check above example if there is an [ Edit table ] button below the table in above example
Click on [ Edit table ], make changes and save the table
docfix: the documentation page was an old one - CN
13 Oct 2003:
bugfix: %-vars in select were resetted to first on add/del row - CN
18 Sep 2003:
incompatibility: changed default of changerows to on; support for %-vars, Quiet save for saving without notification; all other fixes in Dev topic integrated - CN
08 Nov 2002:
Prevent variable expansion in label text; added escape characters
27 Jun 2002:
New helptopic parameter
26 Jun 2002:
Support for variables in included EDITTABLE parameters; fixed problem with HTML in cells
21 May 2002:
Added fixed label format; new changerows="add" parameter
27 Apr 2002:
Fixed bug where text after a double quote in a cell disappeared
18 Apr 2002:
Fixed bug where table was breaking when pasting multiple lines into an edit field using Netscape on Unix
08 Apr 2002:
Check for change permission and edit lock of topic
05 Apr 2002:
Initial version
CPAN Dependencies:
none
Other Dependencies:
Mishoo DHTML calendar (version 0.9.5 preinstalled); TWiki version 01 Feb 2003 or later
This is an empty plugin you can use as a template to build your own TWikiPlugins. This plugin does nothing, but is ready to be used.
To create your own plugin:
Copy file TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm and customize the plugin.
Create a <name>Plugin topic in the TWiki web. Do so by visiting http://TWiki.org/cgi-bin/view/Plugins/ and starting a new topic to get the default plugin topic text (don't save the topic). Customize your plugin topic to your needs.
Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, for example, %EMPTYPLUGIN_SHORTDESCRIPTION%
Set SHORTDESCRIPTION = This plugin does nothing, but can be used as a template for your own plugins.
Your own settings, for example:
Set EXAMPLE = got it!
Debug plugin: (See output in data/debug.txt)
Set DEBUG = 0
Plugin Installation Instructions
(This plugin is preinstalled, you do not need to install it.)
Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
Download the ZIP file from the Plugin web (see below)
Unzip EmptyPlugin.zip in your twiki installation directory. Content:
Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved.
What Are Attachments Good For?
File Attachments can be used to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.
Document Management System
You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using web and topic-level access control; create a central reference library that's easy to share with an user group spread around the world.
File Sharing
For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!
Web Authoring
Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to link to on a page) and place them on a single page, or use them across a web, or site-wide.
NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires FTP access, and may be more convenient if you have a large number of files to load. FTP-ed files can't be managed using browser-based Attachment controls. You can use your browser to create TWikiVariables shortcuts, like this %H% = .
Uploading Files
Click on the Attach link at the bottom of the page. The Attach screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the File Attachment table.
Any type of file can be uploaded. Some files that might pose a security risk are renamed, ex: *.php files are renamed to *.php.txt so that no one can place code that would be read in a .php file.
The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.
Currently there is no file size limit other than the disk space on the server.
* It's not recommended to upload files greater than a few hundred K through a browser. Large files can be extremely slow-loading, and often time out. Use FTP for large file uploads.
NOTE: There is no access control on individual attachments. If you need control over single files, create a separate topic per file and set topic-level access restrictions for each.
Moving Attachment Files
An attachment can be moved between topics.
Click Action on the Attachment to be moved.
On the control screen, select the new web and/or topic.
Click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Deleting Attachments
It is not possible to delete attached files directly. You can delete a topic, and its attachments with it.
One easy workaround is to create a Trash.TrashAttachments - then, simply move unwanted Attachments to that topic.
Linking to Attached Files
Once a file is attached it can be referenced in the topic. Example:
GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
Attach file: Smile.gif
Edit topic and write text: %ATTACHURL%/Smile.gif
Preview: text appears as , an image.
File Attachment Contents Table
Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.
Clicking on an Action link takes you to a new page that looks like this:
The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.
The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.
Known Issues
Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute includes h then the attachment is considered to be hidden. It is not listed in the topic, but is displayed when attach page is displayed.
-- JohnTalintyre - 30 Aug 2001
Inline search feature allows flexible formatting of search result
The %SEARCH{...}% variable documented in TWikiVariables has a fixed format for the search result, that is, a table consisting of topic names and topic summaries. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (such as %SEARCH{ "food" format="| $topic | $summary |" }%).
Syntax
Two parameters can be used to specify a customized search result:
1. header="..." parameter
Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. Example: header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format parameter to specify the format of one search hit.
Example: format="| $topic | $summary |"
Variables that can be used in the format string:
Topic name, hyphenated each 30 characters with separator "-<br />"
$topic(40, ...)
Topic name, shortended to 40 characters with "..." indication
$text
Formatted topic text
$locked
LOCKED flag (if any)
$date
Time stamp of last topic update, like 08 May 2009 - 00:57
$isodate
Time stamp of last topic update, like 2009-05-08T00:57Z
$rev
Number of last topic revision, like 1.4
$wikiusername
Wiki user name of last topic update, like Main.JohnSmith
$username
User name of last topic update, like JohnSmith
$summary
Topic summary
$formfield(name)
The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$formfield(name, 10)
Form field value, "- " hyphenated each 10 characters
$formfield(name, 20, -<br />)
Form field value, hyphenated each 20 characters with separator "-<br />"
$formfield(name, 30, ...)
Form field value, shortended to 30 characters with "..." indication
$pattern(reg-exp)
A regular expression pattern to extract some text from a topic. For example, $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....
$n or $n()
New line
$nop or $nop()
Is a "no operation". This variable gets removed; useful for nested search
$quot
Double quote ("). Alternatively write \" to escape it
$percnt
Percent sign (%)
$dollar
Dollar sign ($)
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised; for example, if you include a table make sure to include everything including the table end tag.
TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Table showing form field values of topics with a form
Write this in the Know web:| *Topic:* | *OperatingSystem:* | *OsVersion:* | %SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%To get this:
Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
Nested Search
Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.
Here is an example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).
First search:
%SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
Second search. For each hit we want this search:
%SEARCH{ "(topic found in first search)" format=" $topic" nosearch="on" nototal="on" }%
Now let's nest the two. We need to escape the second search, e.g. the first search will build a valid second search string. Note that we escape the second search so that it does not get evaluated prematurely by the first search:
Use $percnt to escape the leading percent of the second search
TWiki has a GPL (GNU General Public License). What is GPL?
Answer:
TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of the free software licenses that protects the copyright holder, and at the same time allows users to redistribute the software under the terms of the license. Extract:
This program is open source software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
Please note that TWiki is not distributed under the LGPL (Lesser General Public Licence), which implies TWiki can only be used with software that is licensed under conditions compliant with the GPL. Embedding in proprietary software requires an alternative license. Contact the author for details.
Back to:TWikiFAQ
-- PeterThoeny - 27 Nov 2000
OR, by all means, insert your comment where it seems to fit best:
you may want to inset it with a bullet and/or set it in italics so it's clear (always sign and date)
if a sub-topic develops, separate it with a horizontal rule at beginning and end
A good format for a new topic is "dissertation followed by discussion":
start with a brief, factual introduction, followed by double horizontal rules
let the discussion begin
When a discussion dies down and the page becomes static, if you're clear on your course, feel free to refactor mercilessly:
fearlessly edit down to capture the key points
reduce the noise without losing the facts or the flavor
if you merge or delete comments, group credit Contributors: at the end of the page
This is how Wiki content matures and grows in value over time.
For external site links, you can type URLs directly into the text - http://etcete.ra/... - it'll clear to anyone where they're headed on click.
TWiki is intended for world-wide use, and an international standard date format like 01 Sep 2001 is preferred. It's universally understood, and clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
TIP: Check the source when you want to find out how something is formatted: click Edit on the lower toolbar. To see earlier versions, click More, then check Raw text format and click View revision. A bit of HTML experience can't hurt, but you'll soon see with TWikiShorthand how far that is from necessary.
Include Topics and Web Pages Using %INCLUDE{...}% Variable
Use the %INCLUDE{...}% variable to embed the content of another topic or web page inside a TWiki topic. The whole content or only parts of a page can be included. If needed, set a proxy server in TWikiPreferences.
"page":
The nameless parameter specifies the page to include. It is
The name of a topic located in the current web, e.g., %INCLUDE{"WebNotify"}%
A Web.Topic name specifying a topic in another web, e.g., %INCLUDE{"TWiki.SiteMap"}%
A full qualified URL with http protocol, domain name and optional port number, e.g., %INCLUDE{"http://twiki.org:80/index.html"}%. Supported content types are text/html and text/plain. The full page is included by default, but the HTML header and scripts are stripped in case it is a web page.
pattern="reg-exp":
The pattern parameter is optional and allows you to extract some parts of a web page. Specify a RegularExpression that scans from start ('^') to end and contains the text you want to keep in parenthesis, e.g., pattern="^.*?(from here.*?to here).*". You need to make sure that the integrity of a web page is not compromised; for example, if you include a table, make sure to include everything including the table end tag.
rev="1.x":
The rev parameter is optional and allows you to include an earlier revision of a topic. This can be used to include an official version of a topic, e.g. one that has been signed of by management. This parameter does not apply to URLs.
Note: All text of a topic is included unless you specify %STARTINCLUDE%, %STOPINCLUDE% and/or a pattern parameter.
Usage Examples
1. Display regression test results in a TWiki page
Install an Encrypted Password
This form can be used only by the TWikiAdminGroup users to install
an encrypted password generated by a user with ResetPassword.
After submitting this form the user's password will be changed.
Plugins are mainly user-contributed add-ons that enhance and extend TWiki features and capabilities. A limited number of plugins are included in the core TWiki distribution - and most those can be removed - while the rest are optional, available from TWiki:Plugins/WebHome.
Here is a list of the plugins currently installed on this TWiki site:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
These quick enhancements are aimed at improving TWiki's ease-of-use. New TWiki site administrators are especially encouraged to review this document for ideas before deploying a new TWikiSite. The metaphor of building a house is useful. The listed enhancedments are some of the details possible when moving into a new office or home. These small changes can make a big differences for user satisfaction at your site. All modifications can be done through your Web browser, and they don't take more then in a couple of minutes. No system administration expertise is required. Some of these enhancements are also mentioned in the reference manual and other topics.
Many of these tips are based on setting some special TWikiVariables.
We recommend implementing at least some of these enhancements right after installation, to get a taste for what is possible. Some of these tips and enhancements should be implemented before or during initial roll-out.
This may spark your imagination to really customize your site so that it's optimal for your users. Slightly more advanced customization tips are listed in TWikiAdminCookBook.
You need to know what is the variable name, and in what page is/should be defined.
Change Colors of Page Header/Footer
Incredibly obvious, maybe, but some TWiki site admins don't get around to changing the default web colors right off, whether they like them or not. Simply changing the defaults will make a huge difference in the overall look.
What we are doing
We want to set variable WEBBGCOLOR in topic WebPreferences to one of the StandardColors. WebPreferences is, as you can guess, a topic which holds all kind of preference setting for each TWiki Web{*}. Each web has its own WebPreferences, and you can set them differently for each web.
How to do it
Pick color code from company or product references, the StandardColors table (recommended for 8-bit client compatibility), or some other color reference.
Set your preferred WEBBGCOLOR preferences variable, and save the topic.
Add a new line immediately after the color code. If there is (invisible) space after the color code, the page header might get strange colors (e.g. black).
It's just as easy to refine later on, so you're not locked in, just looking better.
Set Page Background Color
Without getting into the TWikiTemplates system yet, you can easily edit the view.tmpl (in the templates directory). In the HTML at the top, the body tag has the page background hardcoded to white bgcolor="#ffffff". You can change that color value to new variable. First, define a new preferences variable in the site-level TWikiPreferences, e.g. * Set =PAGEBGCOLOR = #d0d0d0, then edit the view.tmpl template file and change bgcolor="#ffffff" to bgcolor="%PAGEBGCOLOR%". If you want you can set the page background color individualy per web, simple add a * Set =PAGEBGCOLOR = #d0d0d0 bullet to the WebPreferences to overload the site-level preferences. (Without font color control, you'll have to stick to light colors.
A good first navigation tool for new users, a fast-loading linked list (page titles only) of a web's topics is a quick and easy way see what's available. By default, slower, but more powerfull WebIndex is used.
Without explaining what WEBTOPICLIST is, just try it:
In WEBTOPICLIST variable, replace WebIndex with WebTopicList, and save.
Simple way to create colored text and graphics
This should be enabled, see the "Miscellaneous Settings" in the TWikiPreferences, . If not, look at TWiki:TWiki/TWikiPreferences. Look for variables RED, BLUE etc (which define HTML tag FONT). To copy/paste the variables defining the colors you need to see the source text, but Edit is disabled. Instead, go to More and view the topic in raw format.
EZ Graphic Icons to Highlight Text
Graphics in text (like this: ) is done also by defining special variables. See TWiki.TWikiPreferences. Some may prefer longer names, like HELP, WARN etc. You can also add your own images, e.g. a NEW, or a ASK to ask question.
Using graphic icons to highlight important text right from the start can seriously improve how well new users take to a TWiki site. A minimum set of two or three icons can make content much easier to follow, eye-catching, EXCITING. Research says, people tent not to read pages through, but scan them first - and graphics (used sparringly ;-) of course) can help them. On HELP pages, most people tend to jump around looking for answers rather than reading through - icons help point out the most important bits.
How to create your own set of icons:
Attach a graphic (the ones on this page are 16x16 pixels), then define a Preference Variable with a short but recognizable name.
Example: Enter %TEST% to get %TEST% - see how it's done.
Ideas for quick icons: NEW; UPDATE; a STAR or other bullet; key symbols relating to your site content.
For documentation and help, this TWiki web uses three main icons: for HELP, for TIP, for IMPORTANT.
Related: There are other approaches for creating more extensive TWiki icon libraries. This is a simply and quick way to get started. See TWikiDocGraphics for more info.
Use TOC variable to create table of contens
TOC is Table-Of-Contens, generated automagically from headers (defined like that: ---++ , see TWikiShorthand).
For example, you may want to put all your custom variables in TWikiPreferences right on top of the page, and generate table of contens, like:
Preferences for easy creating nice pages
Graphics icons in text
Colored text
System Preferences
Contents of page header and footer
User interface defaults
Email
Plugins
Notes
Non-admin users wil be interested only in first part, non-system preferences.
Personal Productivity - Tools and Tips for Working Faster
Although this area applies to all TWiki set-ups, the initial focus is on TWiki site managers working on a Linux/Apache TWiki site, from a Windows local PC. The assumption being: if you're working with Linux as your desktop, you're probably a programmer or system admin and have these basics handled!
Use your favorite text editor for major edits
When you have a fair bit of TWiki formatting work - for example, compiling new info pages from various cut'n'paste sources, editing multiple TWiki topics or contributed material - it's often easier to use a real TextEditor instead of the browser's text edit box. There are several methods for doing this. For Windows, there are several well-recommended text editors.
Windows Example:TextPad is a low-cost, top flight Windows program, with an extended trial period. You can download from a well-stocked library of user-contributed macros, dictionaries, and syntax and clip files. You can also easily create a TWiki clip collection that allows you to format text with TWiki code: select a text string and click for bold, italic, links, bullet lists - just like a regular HTML editor - and also insert blocks of TWiki code, use simple or regex search and replace, more.
Copy & Paste: Using the web window this can work very well. System differences may present difficulties with this method but it is simple and reliable in most cases.
Browser Integration: Some web browsers can be configured to automatically use an external editor. See your browser documentation for details. Such a configuration and a small tool for Linux is described in an example on TWiki.org. TWiki:Codev/EditDaemonWithGVimIntegrationAlternate Browser: While your main browser might not have the features for TWikic topic editing, another one might.
An example on the Linux platform is the w3m pager/browser for Linux. This is a text based version similar to lynx but it includes text editor features and a configurable command set to act like lynx if you are more accustomed to it.
Use SEARCH to Create a personal directory of topics you're involved in
Here's how you can create your own personal directory of topics you've contributed to recently. Copy the text below (between Start Copy and End Copy) and paste it into your personal page (Main.guest). You can add other webs to search by duplicating one of the web subsections and editing the string {web ="webname"} in the search parameters to refer to the specific web you want to search. This script would also work for a group.
Start Copy
__Here's a list of topics I've been involved in recently:__
---++++ Codev
%SEARCH{ "InstantEnhancements" web="Codev" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" regex="off" order="modified" reverse="on" limit="20"}%
---++++ Support
%SEARCH{ "InstantEnhancements" web="Support" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" regex="off" order="modified" reverse="on" limit="20"}%
---++++ TWiki
%SEARCH{ "InstantEnhancements" web="TWiki" scope="text" nosearch="on" nosummary="on" noheader="on" nototal="on" regex="off" order="modified" reverse="on" limit="10"}%
End Copy
The SEARCH variable has many more formatting options, see TWikiVariables.
Hidden Edit Lock for Individual Topics
When you're creating main gateway pages, you may want to temporarily (or permanently) restrict editing to yourself or a limited group of people. You can do this with a Preference setting that includes one or more users and groups. Only auhorized users will be able to use Edit.
Approved and already deployed on several TWiki sites, this logo set provides a professional alternative to the Robot.
The size of Robot icon is 46x50 pixels - there are countless 48x48 standard-sized, free-use grapics if you're stuck. Here are some decent places to look. Attach the new graphic to TWikiPreferences, and change the WIKILOGOIMG variable.
Customize Topic Classification Forms
With a simple one or two-line default topic form available for every topic - in Edit mode, click the [Add] button, and select the form if it isn't alredy enabled. Then, click the title to get to the actual form, [Edit], and carefully change values, probably basic page classifications. You'll get some increased value, and hands-on experience with TWikiForms, without having to read up about them first. (add the corresponding search per category - copy a default and change)
Add Your Favorite JavaScript Features
You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the TWikiTemplates system yet, you can easily edit the view.tmpl (in the templates directory) for some dramatic effects. The top of the template is mostly regular HTML with some variables. Open up some space in the <head> area, and you can drop in reliable JavaScripts - a pop-up window script, for example - or tag it as an external script.
Obviously, you can do the same - place a link to an external stylesheet as well. If you set values for standard HTML tags, you can control a good deal of the type size, style and color with out adding CSS tags. example
This topic lists all aliases needed to map Inter-Site links to external wikis/sites.
Whenever you write ExternalSite:Page it will be linked automatically to the page on the external site. The link points to the URL corresponding to the ExternalSite alias below, concatenated to the Page you choose. Example: Type Wiki:RecentChanges to get Wiki:RecentChanges, the RecentChanges page at the original Wiki site.
How to define Inter-Site links
Inter-Site links are defined in the tables below.
Each entry must be of format: | External site alias | URL | Tooltip help text |.
The URL and Tooltip Text may contain optional $page variables; the variable gets expanded to the page name.
Note: The Tooltip Text must not contain any HTML tags (including <nop> escape code), no internal WikiWord links, and no external links. Hint: Escape 'WikiWords' and '$page'.
Plugin settings are stored as Preferences variables. To reference
a plugin setting write %<plugin>_<setting>%, for example, %INTERWIKIPLUGIN_SHORTDESCRIPTION%
E-mail notification: Get automatically notified when something has changed in a TWiki web.
Structured content: Use TWikiForms to classify and categorize unstructured web pages and to create simple workflow systems.
File attachments:Upload and download any file as an attachment to a page by using your browser. This is similar to file attachments in an e-mail, but it happens on web pages.
Revision control: All changes to pages and attachments are tracked. Retrieve previous page revisions; compare differences; find out who changed what and when.
Access control: Define groups and impose fine-grained read and write access restrictions based on groups and users.
Variables: Use variables to dynamically compose your pages. This allows you for example to dynamically build a table of contents, include other pages, or show a search result embedded in a page.
TWiki plugins: Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl using the TWiki Plugin API.
Templates and skins: A flexible templating system separates program logic and presentation. Skins overwrite template headers and footers; page content is unaffected.
Managing pages: Individual pages can be renamed, moved and deleted through the browser.
Browser-based rename, move, and delete for individual topics
Overview
You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden Trash web.
How to Rename/Move/Delete a Topic
Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move]. You can now rename and/or move/delete in one operation:
Move/Delete: Select the target web if other than the current web - choose Trash to delete a topic.
Rename: Enter the new topic name - default is current name NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).
Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
If any of the referring pages are locked then they will be listed: you can correct these later by again pressing [Rename/Move].
There is a Put back feature that allows you to undo a Rename/Move/Delete - an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.
Deleted Topics: How to Clear the Trash
Deleted topics are moved to a special Trash web - they are NOT physically erased from the server. All webs share Trash - in case of a name conflict with a topic already Trash, the user is alerted and asked to choose a new name.
The Trash web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the Trash directory.
This can only be done from on the server, not through the browser.
Since simple FTP access to the Trash directory is all that's required for maintenance, it's possible to grant Trash admin privileges to multiple users, while strictly limiting server access.
Redirecting from an Old Topic
You can use TWikiMetaData to place a command in the WebTopicViewTemplate and WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED{...}%. Customize something like this:
%<nop>METASEARCH{type="topicmoved" web="TWiki" topic="ManagingTopics"
title="This topic used to exist and was moved to: "}%
How Rename/Move Works
%SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
User can omit one or more topics from the update list by unchecking them.
<pre> and <verbatim> are honoured - no changes are made to text within these areas.
The topic is moved (if locks allow).
References are changed (locks and permissions permitting).
Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.
How Referring Topics Are Found
Referring topics are found using the %SEARCH% variable - see the template searchrenameview.tmpl. First, matching topics in the current web are listed - matches are to topic. Next, all webs (including the current one) are listed that match web.topic. Because %SEARCH% is used, webs marked in WebPreferences as NOSEARCHALL will not show up in the search for references to the topic being changed.
Changed references are kept are as short as possible, ex: topic is used in preference to web.topic.
Effect of User Access Settings
User permissions affect the Rename function in various ways. To rename a topic, you need both ALLOWTOPICCHANGE and ALLOWTOPICRENAME permission for that topic. To alter referring topics, you need change permission. See TWikiAccessControl for information on setting up access permissions.
Special Considerations
Consider carefully whether to make browser-based Rename/Move/Delete widely available, or to restrict it to an administrator/moderator group. Allowing all users to easily manipulate topics can be extremely useful in refactoring a busy web or site. However, there are at least two significant potential drawbacks to take into account:
When referring links are updated, the modified topics appear in WebChanges, creating the impression that editorial changes were made. This can undermine the usefulness of WebChanges.
Due to current limitations, fairly heavy use of Rename/Move/Delete functions can lead to an accumulation of minor technical problems (ex: broken links) and usability issues (ex: user confusion). If Rename... is used heavily, these negatives will obviously increase, in number and effect.
Ultimately, the size, objectives, and policies of your TWiki site, the real-world behavior of your user group, and most importantly, the initial TWiki site management leadership, will determine the most effective implementation of this feature, and the success of the site overall.
Known Issues
Rename/Move is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that search can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]]
[[old topic]] => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]] => [[NewTopic]]
Adding webs is a web based operation; renaming and deleting webs are manual operations done directly on the server
Overview
A TWikiSite is divided into webs; each one represents one subject, one area of collaboration. Administrators can add/rename/delete webs.
Choose Web Template
There are two methods used to create a new web. First you can use a specially designed TemplateWeb. This is an invisible web that begins with an underscore "_" character. All topics in the _default template web will be copied into your new web.
The second method is to use an existing web as a template web. This may be useful if you already have a web that you like to use as a starting point. Only topics that have names beginning with Web... (like "WebHome", "WebNotify", etc.) are copied.
In either case you will want to be sure to verify that your new web has all the custom modifications that you desire.
Adding a New Web
Note: Attachments will NOT get copied over along with their topics. This will be a feature added for the TWiki:Codev/CairoRelease.
Note: This script does not yet edit the TWiki.TWikiPreferences file to update the WIKIWEBLIST. This must be done by hand.
The manage script while creating the new web will update the following variables in the WebPreferences: WEBBGCOLOR, SITEMAPLIST, SITEMAPWHAT, SITEMAPUSETO and NOSEARCHALL. These variables are now used to dynamically generate the SiteMap.
Renaming or Deleting a Web
Renaming or deleting a web requires direct access to the installation files on the host server. There are currently no browser-based equivalents of the Rename/move/delete topic tools for working with webs.
NOTE: If you plan to rename the TWiki.Main web, remember that TWiki stores user and group topics in %MAINWEB%, default named Main. That means, every WikiName signature - Main.SomeUserName - points to it and would need updating (unless the variable, %MAINWEB%.SomeUserName, is used throughout).
Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic.
Make changes as required, to Newwebname.SomeTopic or better yet, to %MAINWEB%.SomeTopic.
Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable.
Login to the TWiki server, via Telnet or FTP.
Go to twiki/data and rename or remove the web directory.
Go to twiki/templates and rename or remove the web directory if present.
Go to twiki/pub and rename or remove the web directory if present.
Various meta data can be stored in topics - MetaDataDefinition
This is rendered using the %META% variable. This is mostly used in the view, preview and edit scripts.
At present support is fairly basic:
Show attachments, excluding hidden ones. Options: all="on": Show all attachments i.e. including hidden ones
%META{"moved"}%
Details of any topic moves
%META{"parent"}%
Show topic parent. Options: dontrecurse="on": By default recurses up tree, this has some cost. nowebhome="on": Suppress WebHome. prefix="...": Prefix that goes before parents, but only if there are parents, default "". suffix="...": Suffix, only appears if there are parents, default "". separator="...": Separator between parents, default is " > ".
Possible future additions:
Rendering of form data to alternate formats e.g. bullet lists
Background Image for Preview
Preview looks like the real page, but the links leed to an oops dialog warning users of not yet saved topics. In addition, a background with a "PREVIEW" watermark is shown to have visual clue that you are previewing a topic. You can change the background image by specifying the name of an attached background image file in the PREVIEWBGIMAGE variable in the TWikiPreferences.
Remarks:
You also could attach a new image file to this topic.
You can override the PREVIEWBGIMAGE preference variable in your personal home page.
Regular expressions (REs), unlike simple queries, allow you to search for text which matches a particular pattern.
REs are similar to (but more poweful than) the "wildcards" used in the command-line interfaces found in operating systems such as Unix and MS-DOS. REs are used by sophisticated search engines, as well as by many Unix-based languages and tools ( e.g., awk, grep, lex, perl, and sed ).
Examples
compan(y|ies)
Search for company, companies
(peter|paul)
Search for peter, paul
bug*
Search for bug, bugs, bugfix
[Bb]ag
Search for Bag, bag
b[aiueo]g
Second letter is a vowel. Matches bag, bug, big
b.g
Second letter is any letter. Matches also b&g
[a-zA-Z]
Matches any one letter (but not a number or a symbol)
[^0-9a-zA-Z]
Matches any symbol (but not a number or a letter)
[A-Z][A-Z]*
Matches one or more uppercase letters
[0-9]{3}-[0-9]{2}-[0-9]{4}
US social security number, e.g. 123-45-6789
PNG;Chart
Search for topics containing the words PNGandChart. This is not a regular expression! But a useful facility that is enabled when regular expression searching is enabled.
Searches with "and" combinations
TWiki extends the regular expressions with an and search. The delimiter is a semicolon ;. Example search for "form" and "template": form;template
Use Google if your TWiki site is public. Example search for "form" and "template" at TWiki.org: site:twiki.org +form +template
Advanced
Here is stuff for our UNIX freaks: (copied from 'man egrep')
A regular expression is a pattern that describes a set of strings. Regular expressions are constructed analogously to arithmetic expressions, by using various operators to combine smaller expressions.
The fundamental building blocks are the regular expressions that match a single character. Most characters, including all letters and digits, are regular expressions that match themselves. Any metacharacter with special meaning may be quoted by preceding it with a backslash.
A bracket expression is a list of characters enclosed by [ and ]. It matches any single character in that list; if the first character of the list is the caret ^ then it matches any character not in the list. For example, the regular expression [0123456789] matches any single digit.
Within a bracket expression, a range expression consists of two characters separated by a hyphen. It matches any single character that sorts between the two characters, inclusive, using the locale's collating sequence and character set. For example, in the default C locale, [a-d] is equivalent to [abcd]. Many locales sort characters in dictionary order, and in these locales [a-d] is typically not equivalent to [abcd]; it might be equivalent to [aBbCcDd], for example.
Finally, certain named classes of characters are predefined within bracket expressions, as follows. Their names are self explanatory, and they are [:alnum:], [:alpha:], [:cntrl:], [:digit:], [:graph:], [:lower:], [:print:], [:punct:], [:space:], [:upper:], and [:xdigit:]. For example, [[:alnum:]] means [0-9A-Za-z], except the latter form depends upon the C locale and the ASCII character encoding, whereas the former is independent of locale and character set. (Note that the brackets in these class names are part of the symbolic names, and must be included in addition to the brackets delimiting the bracket list.) Most metacharacters lose their special meaning inside lists. To include a literal ] place it first in the list. Similarly, to include a literal ^ place it anywhere but first. Finally, to include a literal - place it last.
The period . matches any single character. The symbol \w is a synonym for [[:alnum:]] and \W is a synonym for [^[:alnum]].
The caret ^ and the dollar sign $ are metacharacters that respectively match the empty string at the beginning and end of a line. The symbols \< and \> respectively match the empty string at the beginning and end of a word. The symbol \b matches the empty string at the edge of a word, and \B matches the empty string provided it's not at the edge of a word.
A regular expression may be followed by one of several repetition operators:
?
The preceding item is optional and matched at most once.
*
The preceding item will be matched zero or more times.
+
The preceding item will be matched one or more times.
{n}
The preceding item is matched exactly n times.
{n,}
The preceding item is matched n or more times.
{n,m}
The preceding item is matched at least n times, but not more than m times.
Two regular expressions may be concatenated; the resulting regular expression matches any string formed by concatenating two substrings that respectively match the concatenated subexpressions.
Two regular expressions may be joined by the infix operator |; the resulting regular expression matches any string matching either subexpression.
Repetition takes precedence over concatenation, which in turn takes precedence over alternation. A whole subexpression may be enclosed in parentheses to override these precedence rules.
The backreference \n, where n is a single digit, matches the substring previously matched by the nth parenthesized subexpression of the regular expression.
Request for reset of password
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will see a page with your new password appearing encrypted.
You will have to e-mail this information to the Wiki webmaster caad-yearly@hbt.arch.ethz.ch , who will set your account to use the new password.
I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem.
Answer:
That is an indication that TWiki can't find the egrep and fgrep commands on your system. Check the $egrepCmd and $fgrepCmd variables in twiki/lib/TWiki.cfg.
Back to:TWikiFAQ
-- PeterThoeny - 26 Jan 2001
What happens if two of us try to edit the same topic simultaneously?
Answer:
The second person gets a warning that the topic is currently being edited by another user. A topic gets locked automatically for some time (default is one hour) when you edit, preview or save the topic. If you get the lock warning you should wait until the lock is gone or contact the other person to ask if you can go ahead and break the lock. See also UnlockTopic.
Back to:TWikiFAQ
-- PeterThoeny - 27 Nov 2000
...discover TWiki details, and how to start your own site.
You can use color coding by web for identification and reference. This table is updated automatically based on WebPreferences settings of the individual webs. Contact caad-yearly@hbt.arch.ethz.ch if you need a separate collaboration web for your team.
You can automatically generate usage statistics for all webs. To enable this:
Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in wikicfg.pm are set. This will generate log entries in file twiki/data/log<date>.txt .
Topic WebStatistics must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry: 0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example: 0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
Update current month for all webs: http://mydomain.com/twiki/bin/statistics
Update current month for Main web only: http://mydomain.com/twiki/bin/statistics/Main
Update January 2000 for Main web: http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
Welcome to TWiki. This page assumes that you are a new user to TWiki, and that you've never heard of Wiki before. Here are the most important pages you should know about to get you up to speed on what Wiki is, and how to use it. Follow any of the links below that interest you and use your browser's back button to return to this page if you need to.
WelcomeGuest: A brief intro for first-time visitors
Restricting read and write access to topics and webs, by Users and groupsTWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user Groups, in three areas: view; edit & attach; and rename/move/delete. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.
An Important Control Consideration
Open, freeform editing is the essence of WikiCulture - what makes TWiki different and often more effective than other collaboration tools. For that reason, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care - the more restrictions, the less Wiki in the mix. Experience shows that unrestricted write access works very well because:
Peer influence is enough to ensure that only relevant content is posted.
Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focussed.
In TWiki, content is transparently preserved under revision control:
Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a collaboration guideline:
Create broad-based Groups (for more and varied input), and...
Avoid creating view-only Users (if you can read it, you should be able to contribute to it).
Users and Groups
Access control is based on the familiar concept of Users and Groups. Users are defined by their WikiNames. They can then be organized in unlimited combinations by inclusion in one or more user Groups. For convenience, Groups can also be included in other Groups.
Managing Users
A user can create an account in TWikiRegistration. The following actions are performed:
WikiName and encrypted password are recorded in .htpasswd if authentication is enabled.
A confirmation e-mail is sent to the user.
A user home page with the WikiName of the user is created in the Main web.
Users can be authenticated using Basic Authentication (htaccess) or SSL (secure server). In either case, TWikiUserAuthentication is required in order to track user identities, and use User and Group access control.
The default visitor name is TWikiGuest. This is the non-authenticated user.
Managing Groups
Groups are defined by group topics created in the Main web, like the TWikiAdminGroup. To create a new group:
EditTWikiGroups by entering a new topic with a name that ends in Group. Example:
SomeGroup
Set Preferences for two Variables in the new group topic:
Set GROUP = < list of Users and/or Groups >
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
The GROUP variable is a comma-separated list of Users and/or other Groups. Example:
Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of Users and Groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. (This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:
Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
Restricting Write Access
You can define who is allowed to make changes to a web or a topic.
Deny Editing by Topic
Denying editing of a topic also restricts file attachment; both privileges are assigned together.
Define one or both of these variables in a topic, preferably at the end of the page:
Set DENYTOPICCHANGE = < list of Users and Groups >
Set ALLOWTOPICCHANGE = < list of Users and Groups >
DENYTOPICCHANGE defines Users or Groups that are not allowed to make changes to the topic, with a comma-delimited list. Example:
Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICCHANGE defines Users or Groups that are allowed to make changes to the topic. It is a comma delimited list of Users and Groups. Example:
Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.
Deny Editing by Web
Restricting web-level editing blocks creating new topics, changing topics or attaching files.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBCHANGE = < list of Users and Groups >
Set ALLOWWEBCHANGE = < list of Users and Groups >
The same rules apply as for restricting topics, with these additions:
DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)
Restricting Rename Access
You can define who is allowed to rename, move or delete a topic, or rename a web.
Deny Renaming by Topic
To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.
Define one or both of these variables in a topic, preferably at the end of the topic:
Set DENYTOPICRENAME = < list of Users and Groups >
Set ALLOWTOPICRENAME = < list of Users and Groups >
DENYTOPICCRENAME defines Users or Groups that are not allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICRENAME defines Users or Groups that are allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICRENAME is evaluated before ALLOWTOPICRENAME. Access is denied if the authenticated person is in the DENYTOPICRENAME list, or not in the ALLOWTOPICRENAME list. Access is granted in case DENYTOPICRENAME and ALLOWTOPICRENAME is not defined.
Deny Renaming by Web
You can define restrictions of who is allowed to rename a TWiki web.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBRENAME = < list of Users and Groups >
Set ALLOWWEBRENAME = < list of Users and Groups >
The same rules apply as for topics, with these additions:
DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)
Restricting Read Access
You can define who is allowed to see a web.
Deny Viewing by Topic
Technically it is possible to restrict read access to an individual topic based on DENYTOPICVIEW / ALLOWTOPICVIEW preferences variables, provided that the view script is authenticated. However this setup is not recommended since all content is searchable within a web - a search will turn up view restricted topics.
Deny Viewing by Web
You can define restrictions of who is allowed to view a TWiki web. You can restrict access to certain webs to selected Users and Groups, by:
obfuscating webs: Insecure but handy method to hide new webs until content is ready for deployment.
authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.
Obfuscate Webs
The idea is to keep a web hidden by not publishing its URL and by preventing the all webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences:
Set NOSEARCHALL = on
This setup can be useful to hide a new web until content its ready for deployment.
Obfuscating webs is insecure, as anyone who knows the URL can access the web.
Authenticate all Webs and Restrict Selected Webs
Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs:
Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
Note:DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
Set NOSEARCHALL = on
Addview to the list of authenticated scripts in the .htaccess file.
This method only works if the view script is authenticated, which means that all Users have to login, even for read-only access. (An open guest account, like TWikiGuest, can get around this, allowing anyone to login to a common account with, for example, view-only access for public webs.) TWikiInstallationGuide has more on Basic Authentication, using the .htaccess file.
Authenticate and Restricting Selected Webs Only
Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs:
Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
Note:DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
Set NOSEARCHALL = on
Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. TWiki will now remember the IP address of an authenticated user.
Copy the view script to viewauth (or better, create a symbolic link)
Addviewauth to the list of authenticated scripts in the .htaccess file. The view script should not be listed in the .htaccess file.
When a user accesses a web where you enabled view restriction, TWiki will redirect from the view script to the viewauth script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth script shows the requested topic if the user could log on and if the user is authorized to see that web.
Authenticating webs is not very secure, as there is a way to circumvent the read access restriction. It can be useful in certain situations - for example, to simplify site organization and clutter, by hiding low traffic webs - but is not recommended for securing sensitive content.
Hiding Control Settings
To hide access control settings from normal browser viewing, place them in comment markers.
<!-- * Set DENYTOPICCHANGE = Main.SomeGroup -->
The SuperAdminGroup
By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create Web-based superusers:
Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of Users who are always allowed to edit/view topics.
$superAdminGroup = "TWikiAdminGroup";
The default setting is not to have superusers.
-- PeterThoeny - 04 May 2002
-- MikeMannix? - 12 May 2002
This page has many tips and tricks, particularly useful when you're installing TWiki for the first time. This guide is most useful before or immediately following a TWiki installation!
You can rename the Main web to User. It will make WikiWord links to usernames more meaningful (User.UserName instead of Main.UserName); but does not bring much gain for other types of topics like (User.EngineeringGroup or User.TokyoOffice). Just rename data/Main to data/User, and change $mainWebname variable in lib/TWiki.cfg file. Signatures in all existing topics need to be fixed as well.
See also TWiki:Codev.RenameMainWebToHome, TWiki:Codev.RenameTheMainWeb, TWiki:Codev.SeparateHowtoWeb for arguments pro and con.
Help with remembering passwords
Users keep Forgetting Passwords (see TWiki:Codev.ForgettingPasswords ). When demonstrating TWiki to new users and/or helping them with TWikiRegistration, do not forget to show the user how to use the "remember my password" feature in their browser.
A quick way to check the guest password is to view the .htaccess file.
AuthName 'TWiki UserName (i.e. TWikiGuest/guest)'
How to get nice pages with simpler menu options for beginners
A Skin is TWiki's way to present different system-generated formats (like header/footer/sidebar menu) and exactly the same information from the page body (see TWikiSkins). The "Classic" TWiki skin is oriented towards advanced power users. Newbies may feel overwhelmed by the number of options. Many simpler custom skins are in development at TWiki:Plugins.WebHome. Consider using a simpler custom skin to make a better "first impression": TWiki is simple to use.
There is currently a discussion at TWiki:Codev.SimplerDefaultTemplates about simpler default template for TWiki:Codev.SimplerTWikiDistribution.
Customize tutorial for beginners
Select simpler skin and customize beginner's help topics accordingly.
Best of Plugins
With more than 60 TWiki plugins (and counting), there are a lot to choose from. Plugins are mainly contributed by TWiki users who are software developers. Plugins are a relatively new TWiki addition, so there are fewer established standards than for the core TWiki code. This means that not all plugins are equal in ease of installation, operation, or compatibility with each other. Here are selected plugins that are reliable, easy-to-use and offer basic enhanced functionality.
User-friendly alternative of Edit, without losing Wiki spirit. Comments can be entered in a conventional Web form style with a text box and a submit button. This is all displayed on a TWiki page without having to use TWiki's Edit. Text added appears exactly as if edited normally, and topic can be edited also using the full TWiki Edit. This is useful to encourage participation among your users who are not yet comfortable with TWiki capabilities.
This Plugin allows you to convert topics with headings into web based presentations. This is a useful alternative to PowerPoint, especially if you need to link to related content.
This lets you create variables, like a graphics icon library, in any topic - instead of only in WebPreferences - and refer to them from other topics within the same web.
A TWiki contributor is a person devoting his/her time to contribute on the development of the Open Source project TWiki, hosted at http://TWiki.org/ . It is defined as a person who:
has contributed code that was accepted into the TWiki distribution, or
has considerably contributed to the TWiki documentation.
I would like to take this opportunity to express my appreciation to all who contributed ideas, code, fixes and documentation.
This is one way to create a library of common icons, accessible through user-defined TWikiVariables set in WebPreferences, or in TWikiPreferences for site-wide use.
There are other approaches as well: the TWiki:Plugins/TopicVarsPlugin lets you set variables in any topic, not just in WebPreferences, for use in the same. The TWiki:Plugins/SmiliesPlugin, using a different short hand than %VARIABLES%, may be worth checking out for extended use.
In this example, TWikiDocGraphics - this topic - acts as the icon library. Graphics are uploaded and displayed. Then, the paths are set in TWiki.TWikiPreferences#DocGraphics for site-wide access. You can also create individual library pages in each web. And you don't have to restrict yourself to graphics: Preferences Variables can include text and links to any type of file.
Help
Tip / Idea
Warning / Important
Refactor / Edit
Done
Updated
New
Highlight (positive)
Moved to...
View topic
Edit topic
New topic
Search topic
Print topic
Attach file
-- PeterThoeny - 17 Jan 2003
-- MikeMannix? - 16 May 2002
Server and client requirements for TWiki 01-Feb-2003
Low client and server requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions.
Server Requirements
TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements.
*Current documentation mainly covers Linux and Apache installations. See WindowsInstallCookbook for a Windows installation guide. See TWiki:Codev.TWikiOn for help with installation on various platforms including Unix, MacOS X, Apache mod_perl, web hosts, etc.
generates XHTML 1.0 pages that are compatible with HTML 3.2
minimal use of JavaScript in the user interface (degrades gracefully)
no cookies
no CSS
You can easily add functionality, by customizing TWikiTemplates, for one, while tailoring the browser requirements to your situation.
Known Issues
The TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
Plugins included in the TWiki distribution do not add requirements.
Installation instructions for the TWiki 01-Feb-2003 production release. Update notes for the new RCS configuration are markedDataframework.
These installation steps are based on the Apache web server on Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the system requirements. Documentation for other platforms is somewhat limited:
NOTE:If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.
Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file /etc/httpd/httpd.conf with only ExecCGI option.
The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
NOTE: The ScriptAliasmust come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
The twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.
Example httpd.conf entries:
ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
Alias /twiki/ "/home/httpd/twiki/"
<Directory "/home/httpd/twiki/bin">
Options +ExecCGI
SetHandler cgi-script
Allow from all
</Directory>
<Directory "/home/httpd/twiki/pub">
Options FollowSymLinks +Includes
AllowOverride None
Allow from all
</Directory>
<Directory "/home/httpd/twiki/data">
deny from all
</Directory>
<Directory "/home/httpd/twiki/templates">
deny from all
</Directory>
Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.
To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:
Download and unzip TWiki on your local PC
Using the table below, create a directory structure on your host server
Upload the TWiki files by FTP (transfer as text except for the image files in pub)
If you are not able to create the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access), you can create this directory elsewhere and edit the setlib.cfg file in the bin directory:
# -------------- Change these settings if required
$twikiLibPath = '/some/other/path/lib'; # Path to lib directory containing TWiki.pm
You can also edit $localPerlLibPath in the setlib.cfg file if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.
Step 2: Set File Permissions
Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
IMPORTANT: On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary.
Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
replace user twiki with your own username
Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using perl:
cd twiki/data
perl -pi~ -e 's/nobody:/www-data:/' */*,v
Step 3: Set the Main Configuration File
Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
Set the file extension in the $scriptSuffix variable to cgi or pl if required.
RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
Set $storeTopicImpl = "RcsLite"; for the Perl based RCS
Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.
Step 4: Configure Site-Wide Email Preferences
From your web browser, edit the TWikiPreferences topic in the TWiki:TWiki web to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
WIKIWEBMASTER should be set to the email address of the TWiki administrator
SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.
Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
Enable email notification of topic changes, TWikiSiteTools has more.
Edit the WebNotify topic in all webs and add the users you want to notify.
That's it for the standard virgin installation of TWiki. Read on for server-level customization options.
Additional Server-Level Options
With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.
Enabling Authentication of Users
If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly: Redirect /urlpathto/twiki/index.html http://yourdomain.com/urlpathto/twiki/bin/view AuthUserFile /filepathto/twiki/data/.htpasswd ErrorDocument 401 /urlpathto/twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.
The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.
This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.
NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.
Copy the TWikiRegistrationPub? topic to TWikiRegistration, overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
Customization:
You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
You can customize the default user home page in NewUserTemplate.
NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
Create a new topic to check if authentication works.
Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
Edit the WebPreferences topic in each web, if necessary: set access priviliges.
That's it for a basic new web set-up!
Optionally, you can also:
Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.
NOTE: User home topics are located in the TWiki.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!
TWiki File System Info
See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution.
-- PeterThoeny - 28 Dec 2002
-- MikeMannix? - 16 May 2002
Windows Install Cookbook
Introduction
This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as possible. The 'cookbook' approach is simply to restrict the many choices that someone installing TWiki must make, so that a reasonably well-defined procedure can be followed - new users can simply follow the steps, while experts can use this as more of a guideline. Please read TWiki:Codev.WindowsModPerlInstallCookbook in case you use mod_perl.
There is a huge volume of existing material on TWiki about installing on Windows, and I'm indebted to the many contributors for this - the aim of this cookbook is to synthesise the many tips into a recipe that works.
NOTE: This cookbook is probably incomplete (e.g. it doesn't cover authentication setup), but it has now been successfully tried out by a few people - it is quite accurate and should get you started if you follow the instructions. Please consider it beta quality, and provide feedback in TWiki:Codev.WindowsInstallCookbookComments.
NOTE: You will get the best results from following this cookbook exactly, using the same directories etc - however, if you really do need to vary things, it should be fairly obvious what to do.
20 Jul 2002 - added flags to grep commands in TWiki.cfg
27 Jun 2002 - more updates to list of required Cygwin packages
20 Jun 2002 - added creation of c:/twiki directory
17 Jun 2002 - updates to list of required Cygwin packages
15 Jun 2002 - various notes on Cygwin installation and troubleshooting: use of 'Unix' as default text file type (i.e. for mounting c:/cygwin directories) is essential for binary attachment uploads to work properly
27 Apr 2002 - update to settings for egrep and fgrep on some Cygwin versions (fix from TWiki:Main.DavidLeBlanc)
18 Apr 2002 - updates on Apache installation, setting TZ variable, and creation of c:\temp, based on comments by TWiki:Main.MaryDeMarco
3 Apr 2002 - added pcre to list of Cygwin packages (required by grep), fixed bug in Apache config (Apache doesn't allow '#' comments on same line as config)
19 Mar 2002 - comment about Windows 98
18 Mar 2002 - fix for register script committed to TWiki:Codev.TWikiAlphaRelease - most users can ignore this for now, but the edits in step 5 will eventually go away
14 Mar 2002 - minor fix to section on Apache environment
13 Mar 2002 - added a link to another Windows text editor
4 Mar 2002 - changed status to beta, notes about using spaces in file names, pointer on TWiki authentication setup, overview of Cygwin permissions and security issues
3 Mar 2002 - minor update to include uname -a command to check Cygwin DLL version, and delete Apache config's PassEnv line
25 Feb 2002 - clarified changes required to register, fixed minor typo in Cygwin binary mode section, after beta testing by TWiki:Main.JerryWard (thanks!)
Scope
This document covers installation of the TWiki -1-Feb-2003 production release in the following environment - if you want to use a different environment, feel free to use this as a guideline only.
Windows-specific security holes fixed in this build (check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet)
Unix tools
Cygwin 1.3.9
Simplest way to get a whole set of required tools
Perl
Cygwin perl-5.6.1-2
Comes with Cygwin
RCS
Cygwin rcs-5.7-2
Comes with Cygwin, includes a file corruption bugfix
Why this choice of packages? Because I've tried them, and they work well, without requiring a complicated setup... In particular, Apache is the commonest choice for TWiki on Unix/Linux, Cygwin Perl is very close to Unix Perl, and the Cygwin RCS is regularly updated, with a recent TWiki-relevant bug fix in Feb 2002. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time.
More recent minor versions should be OK, but they can introduce bugs.
Major version upgrades, such as Apache 2.0 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate (see TWiki:Support.FailedAuthenticationWithApache2OnWinNT) users created by the current TWiki user registration script (due to a feature being removed in 2.0), and Perl 5.8 may introduce issues due to its Unicode features. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki.
Alternatives
There are doubtless other combinations of components that may work - in particular:
Using a different web server is certainly possible, but the setup required for each webserver varies greatly (see TWiki:Codev.TWikiOnWindows for pages about specific web servers). You may find it easiest to get a working system with Apache and then switch over to another web server.
Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.
Checking versions
If you already have some of these add-ons installed, here's how to check the versions - this assumes you have TWiki:Codev.CygWin already installed:
$ : Cygwin DLL version is the number in 1.3.x format
$ uname -r
$ less c:/your-apache-dir/Announcement
$ perl -v
$ rcs -V
If you have an older version of any component, do yourself a favour and upgrade it as part of the install process.
Pre-requisites and upgrades
You will need to have local administrator rights and to be comfortable with Windows administration.
This cookbook is intended for a clean install, i.e. none of these components are already installed. However, since Cygwin and Apache's installation process is fairly upgrade-friendly, upgrades should work as well - take backups of all your data and config files first, though!
Text editing
Editing Cygwin files is best done with an editor that can handle Unix file format (see the Cygwin binary mode section below) - the installation process includes nano, a non-GUI editor, but if you prefer to use a GUI editor, you should first install PFE, a freeware editor that supports Unix format files. PFE is available on download.com and Simtel.
Another good TWiki:Codev.OpenSource editor is SciTE (aka WSciTE), available at http://www.scintilla.org/SciTE.html.
The Unix/Windows Environment
It's a little known fact that you can use pathnames such as c:/apache almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Win2000 cmd.exe command line shell - here, you must use double quotes around forward slashes, e.g. dir "c:/apache" will work fine.
The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.
The Cygwin environment
TWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support the c:/apache format, but it also provides a more Unixlike syntax, e.g. /usr/bin/rcs.exe, because some Unix tools ported onto Cygwin only support the Unix format.
When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.
The Apache environment
Apache runs as a native Windows process and has nothing to do with Cygwin (at least the version used in this cookbook doesn't). Hence it supports c:/ pathnames in its config files and the first line of Perl CGI scripts.
If you need to use spaces in file names (not recommended), put double quotes around the file name in the httpd.conf file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.
The Perl environment
Once Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, including ls, egrep, and RCS tools that it (typically) launches with the bash shell.
If you need to use spaces in file names (not recommended), you may be able to put double quotes around the file name in the TWiki.cfg file - however, it's not clear whether all the TWiki code would work with this.
Installing Components
Enough background, let's get on with the installation.
TWiki (part 1)
Head to http://twiki.org, click the download link, and fill in the form to request a URL for download. You'll get an automated email, which should arrive by the time you need it.
The file to download is apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher
Note that this is a Microsoft Installer format file (.MSI) - this is supported by Windows 2000.
NOTE: If you are using Windows NT, download the .MSI installer (instmsi.exe) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.
NOTE: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed.
2. Install Apache
Double-click the .MSI file to run the installer
Specify c:\ as the installation directory - this actually installs Apache into c:\apache (if you specify c:\apache, it installs into c:\apache\Apache). Putting Apache into c:\Program Files is not recommended for easy editing of Apache config files from Cygwin.
You can choose to run Apache as a Win2000 service or as a normal program - see the Apache docs for details.
If necessary, start apache, either as a Win2000 service (using Admin Tools | Computer Management, or by typing apache -k start -n apache) or standalone (by typing apache -k start)
Congratulations, you now have a working web server!
To restart Apache after changing its config, type:
apache -k restart for standalone Apache process running in another window
apache -k restart -n apache for Apache running as a Win2000 service (-n gives name of service)
Another useful command is apache -k stop.
Cygwin, Unix tools, Perl and RCS
4. Install Cygwin
Head to http://cygwin.com, and click the Install Cygwin Now link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist.
Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.
Choose Internet install
On first page, accept the defaults (be sure that the default text file type is Unix to avoid problems with attachment uploads, and specify 'install for all users')
Select c:\download\cygwin-dist as the local package directory, and suitable proxy settings, then pick a local mirror site
In the package list screen, hit the View button until you get an alphabetical list that says Full to the right of the button.
Leave the radio button on Curr (Current)
The Current column shows what's installed on your system (if anything)
For each package, make sure the New column in the installer has a version number under it. If it says 'Skip' or 'Keep' (meaning it's already installed), single-click that word until a version number is shown. Make sure you select the following packages:
NOTE: Do not include lynx if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5.
Hit Next to do the installation.
NOTE: The mandatory packages require a download of about 12 MB - about half of this is Perl, which would be necessary even without Cygwin, and most of the rest is gcc, which is required for simple installation of Perl modules that use the C language. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).
NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
Let the installer create the shortcuts suggested
5. Test Cygwin
Launch the desktop icon - this runs the bash shell, which has command line editing features
Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command
TIP: When typing a directory or file name, hit the TAB key after the first few letters of the name - bash will 'complete' the name. If bash beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!
Type rcs -V - you should see the RCS version, 5.7
Type perl -v - you should see cygwin mentioned in the first line, and the Perl version, 5.6.1
Type grep home /etc/passwd - you should see some output.
The Cygwin User Guide is well worth reading for some background on how Cygwin works.
6. Configure Cygwin for binary mode
This is very important - omitting this step leads to a partially working system that corrupts RCS files - without this, Cygwin tools (including Perl and RCS) will add unwanted carriage returns (Ctrl/M, '\r') to files in an attempt to translate between the Windows and Unix text file formats (Unix text files only use line feeds ('\n').
Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'):
$ mkdir /twiki /c c:/twiki
$ mount -b -s c:/twiki /twiki
$ mount -b -s c:/ /c
$ mount -b -c /cygdrive
$ mount
Device Directory Type Flags
C:\cygwin\bin /usr/bin system binmode
C:\cygwin\lib /usr/lib system binmode
C:\cygwin / system binmode
c:\twiki /twiki system binmode
c: /c system binmode
This configures /twiki (known as a 'mount point') to map onto c:/twiki and for that directory tree to always be in binary mode, and does the same for /c, mapping it onto c:/. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/, aka /cygdrive/z).
It is very important that all lines in the output of mount say 'binmode' under Flags
If the lines for C:\cygwin directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.
You can now refer to files using Unix paths, e.g. /twiki/bin/view or /c/apache/Announcement - see the Cygwin documentation for more details on this.
Now test this, still using the Cygwin shell:
Type cd /twiki
Type echo hi >t
Type cat -v t - you should see hi as the output
If you see filename errors, your mounts did not work for some reason - check your typing
If you see hi^M as output, your /twiki directory is not in binary mode
Clean up by doing rm t
This setup is written to the Windows registry, so there's no need to put these commands into a .profile file. For more information on binary vs text mode, see this User Guide section and this FAQ entry.
TWiki (part 2)
7. Download TWiki
Download the latest TWiki release from the URL that PeterThoeny sent you, and save it in the c:/twiki directory.
8. Install TWiki
Unzip the ZIP file under c:/twiki using WinZip, or by going into Cygwin and doing the following - you can hit the TAB key to complete filenames after you've typed the first part:
$ cd /twiki
$ unzip TWiki20011201.zip
Configuring components
Now that all the components are installed, you need to configure them.
Configuring Apache
The setup given here is fairly simple, in that it allows only TWiki to be served by the web server. For more complex setups, you can investigate the Alias and ScriptAlias commands that are left commented out in this configuration.
NOTE: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.
1. Configure Apache (part 1)
Using a suitable text editor (e.g. Cygwin's 'nano', or the Windows PFE editor, unless you already know 'vi'), edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows 2000 environment settings.
If you are using nano, always launch it with nano -w filename - this turns off wrapping of long lines.
Note the trailing '/' characters in various places - they are important!
Create the c:\temp directory, by typing mkdir c:\temp in a DOS command line window
Edit the following lines, some of which already exist in the file:
# Change this to point to the Apache administrator (e.g. you)
ServerAdmin you@yourdomain.com
# Replaces DocumentRoot "C:/apache/htdocs"
DocumentRoot "C:/twiki"
# Replaces <Directory "C:/apache/htdocs">
<Directory "C:/twiki">
Add the following lines - the Alias and ScriptAlias lines can be omitted in this setup
# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory "C:/twiki/bin/">
# RD: Changed None to All in next line, to enable .htaccess
AllowOverride All
Allow From All
Options ExecCGI
SetHandler cgi-script
</Directory>
# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
# Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
# timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT
# during non-daylight-savings time (use '-5' for timezones in advance of GMT).
SetEnv TZ GMT0BST
SetEnv RCSINIT -x,v/
# Adjust TEMP and TMP for your server and create directories if necessary
SetEnv TEMP c:/temp
SetEnv TMP c:/temp
SetEnv LOGNAME system
SetEnv HOME c:/twiki
</IfModule>
2. Configure Apache (part 2)
Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation.
3. Configure TWiki
Edit the TWiki config file, c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:
NOTE: It should be possible to use c:/twiki format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki pathnames with Cygwin, and do report your experiences...
NOTE: Some recent versions of Cygwin (e.g. 1.3.10) seem to create 'symbolic links' from fgrep and egrep to grep, requiring the settings for these commands to point directly to grep (with suitable flags to provide fgrep and egrep behaviour).
# variables that need to be changed when installing on a new server:
# ==================================================================
# http://your.domain.com/twiki : link of TWiki icon in upper left corner :
$wikiHomeUrl = "http://yourdomain.com/bin/view";
# Host of TWiki URL : (Example "http://myhost.com:123")
$defaultUrlHost = "http://yourdomain.com";
# /caadtwiki/bin : cgi-bin path of TWiki URL:
$scriptUrlPath = "/bin";
# /caadtwiki/pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath = "/pub";
# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.
# Public data directory, must match $pubUrlPath :
$pubDir = "/twiki/pub";
# Template directory :
$templateDir = "/twiki/templates";
# Data (topic files) root directory :
$dataDir = "/twiki/data";
....
# Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
# (Note: PATH environment variable is not changed if set to "")
# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.
# Unix/Linux setting:
# $safeEnvPath = "/bin:/usr/bin";
# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin. Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath = "/bin";
# If using ActiveState perl, use Windows paths instead
# $safeEnvPath = "c:/cygwin/bin";
...
# RCS directory (find out by 'which rcs') :
$rcsDir = "c:/cygwin/bin";
...
# Unix egrep command :
$egrepCmd = "/bin/grep -E";
# Unix fgrep command :
$fgrepCmd = "/bin/grep -F";
For the cookbook install using Cygwin Perl, there's no more TWiki.cfg editing to be done, so you can get onto the next section.
For TWiki:Codev.ActiveState Perl, you need to make these additional edits further down the file - this is the only place where backslashes are needed. (See TWiki:Codev.CookbookActivePerlSetup for some extra Perl setup that should remove the need for these edits.)
# NOTE: When using ActiveState Perl, you must specify
# a full Windows-style pathname, using '\\' for backslashes,
# for the ls, egrep and fgrep commands, because Cygwin's shell
# is not used - forward slashes are OK in Windows everywhere
# except in the cmd.exe shell. Drive letters are OK - e.g.
# 'c:\\foo\\ls' will work. When using Cygwin perl, just
# use the default '/bin/ls' type settings.
#
# Unix ls command :
$lsCmd = "c:\\cygwin\\bin\\ls";
# Unix egrep command :
$egrepCmd = "c:\\cygwin\\bin\\grep";
# Unix fgrep command :
$fgrepCmd = "c:\\cygwin\\bin\\grep";
Editing the CGI scripts
4. Editing the Shebang lines
Now to edit the curiously named 'shebang lines' at the top of the TWiki CGI scripts...
You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt)
Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
Type the Perl line very carefully
If you do mis-type the perl line, you can restore from the .backup directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes.
If for some reason the edit goes wrong, just type cp .backup/* . (while within the bin directory) to restore the original distribution files. Use ls -a to see the .backup directory, and ls -a .backup to view its contents.
Optional step: you can do 'rm *~' to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this, type the command very carefully, as a space after the '*' will wipe out all files in this directory!
5. Minor changes to TWiki scripts
As an interlude, you now need to make some minor edits to files in the c:/twiki/bin directory, using a suitable editor (remember to use nano -w filename if you prefer nano to vi - or just use the Windows PFE editor).
Edit the register script in /twiki/bin - change line 200 to read as follows (insert the MIME::Base64:: part):
6. Installing required Perl modules
Some additional Perl modules are needed for the register script to work properly. Fortunately, there is an automated tool that makes it easy to do this - it's called cpan, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them. Here's what you need to do:
First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.
$ export TEMP=/c/temp
$ cpanLots of questions about configuration and preferences - just hit Enter until you
get to the questions about mirror sites, but answer the questions about FTP proxies etc
if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files,
some quite large, as part of this setup process, so be patient...
NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on ncftpget, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running cpan - this forces Net::FTP to use passive FTP, letting it get through such firewalls:
$ export FTP_PASSIVE=1
If this works, add this line to your ~/.profile file for future use.
Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):
...
(28) Turkey
(29) Ukraine
(30) United Kingdom
Select your country (or several nearby countries) [] 30
(1) ftp://cpan.teleglobe.net/pub/CPAN
(2) ftp://ftp.clockerz.net/pub/CPAN/
(3) ftp://ftp.demon.co.uk/pub/CPAN/
(4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
(5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
(6) ftp://ftp.plig.org/pub/CPAN/
(7) ftp://mirror.uklinux.net/pub/CPAN/
(8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
(9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
Select as many URLs as you like,
put them on one line, separated by blanks [] 4 7 8
Enter another URL or RETURN to quit: []
New set of picks:
ftp://ftp.flirble.org/pub/languages/perl/CPAN/
ftp://mirror.uklinux.net/pub/CPAN/
ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
Eventually, you'll get to the CPAN tool's shell prompt, where you need to install a few modules - the tool will do all the work for you.
NOTE: You will need to have previously installed the Cygwin make and gcc packages, which are required by the CPAN installer (gcc is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist (no need to exit the CPAN installer).
cpan shell -- CPAN exploration and modules installation (v1.59_54)
cpan> install Net::SMTPMay already be installed - if it is, try 'force install', since it's useful to be able to set
firewall and passive FTP configuration when using Net::FTP. Make sure you answer 'Y' to the question
about whether you want to configure this package.
cpan> install Digest::SHA1Lots of output about how CPAN finds, builds and installs the module - watch for
any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').
cpan> install MIME::Base64May already be installed.
Re-locking RCS files
7. Re-locking files
First, some testing: in your browser, go to http://yourdomain.com/bin/testenv - this provides a lot of detail, including warnings. Write down the Apache server's userid that is given by this script - typically either 'system' or 'administrator' - I'll assume 'system' from now on.
If the testenv script doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt.
This 'system' user must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. The reason this matters is that no revisions will be tracked by RCS unless the Apache userid matches that of the RCS file locks.
You can re-lock files using rcs -u and rcs -l, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:
NOTE: The 'NR <= 10' part of the Perl command ensures that it only operates on the first 10 lines, to avoid editing the body of RCS files for topics that happen to include the text 'nobody:' (like this one...)
$ cd /twiki/data
$ : Make a backup of all files
$ tar czvf all-files.tar.gz */*
$ : Test edit a single file to check your typing
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v
$ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~
5c5
< system:1.2; strict;
---
> nobody:1.2; strict;
$ : Now edit all the RCS files at once - use cursor-up to recall previous command
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v
$ : Check for any remaining files not edited
$ grep 'strict;$' */*,v | grep -v system
$ : Clean up - type this very carefully
$ rm */*~~~
If something goes wrong: to restore your existing files from the backup, just type tar xzvf all-files.tar.gz and all your files, both .txt and .txt,v, will be back as they were before the edits.
You have now re-locked all the RCS files and are almost ready to start using TWiki!
Email setup
8. Email setup for notification and registration
You need to set the SMTPMAILHOST to an SMTP email host that is reachable and currently working. Otherwise you'll get a confusing message from TWiki when registering new users or running mailnotify (for WebNotify), along the lines of:
Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.
There are other settings to be made in TWikiPreferences, e.g. the WIKIWEBMASTER and (probably) the SMTPSENDERHOST (normally your mail server or TWiki server). See the TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.
Testing your TWiki installation
It is important to test your TWiki installation before you release it to other users or put any significant data into it.
Here are the main things to test:
testenv - use http://yourdomain.com/bin/testenv and check for warnings
Page viewing (view script) - click around a few pages and make sure the links are OK
RCS diffs (rdiff script) - click on the Diffs link and on the '>' links at bottom of page
Edit a page, and register as a new user - tests page creation, use of register script to create a new user entry in /twiki/data/.htpasswd (the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST was set correctly in TWikiPreferences.
If you get a failure to register or send email, check the Apache error log, and that all CPAN modules were installed correctly in Step 6, Installing required Perl modules.
Try typing tail -30 /c/apache/logs/error_log to see last 30 errors from Apache
Edit a page - check revision increased and set to current date/time
Edit the same page using another browser or PC, logging in as a different user - check there's a lock message (which you can override) and no double lines
Check the Apache error_log file to see if there are any RCS errors so far
Index - tests whether ls and grep are working
Search - more tests for whether ls and grep are working
Attachments - tests access to /twiki/pub directory.
Try a binary attachment upload and check the number of bytes in the file has not changed - if it has, see the Install Cygwin section's note on the default text file type.
Check the Apache error_log file again
Troubleshooting
If anything doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt, and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into /twiki/data/debug.txt. There is also a /twiki/data/warning.txt file that contains less serious messages.
See TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g. TWiki:Codev.ChangePasswordOnWin2K).
If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set $egrepCmd and $fgrepCmd correctly, as mentioned above.
By default, it only implements the Unix 'write' and 'execute' permissions bits - the former is controlled by the Windows Read-Only attribute, while the latter is automatically assigned to files named *.exe or *.com, and to files whose first line is a shebang (i.e. #!/bin/something). This is what has been used for this cookbook.
You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.
I have not had any problems with TWiki permissions on Windows, unlike Linux/Unix, which is probably because I'm using the default security model for Cygwin. If you use the other models, you may still be OK if you have local admin rights, and Apache is running as the SYSTEM user (which it uses if started as a service). If you do have trouble in this area, see the TWikiInstallationGuide's advice, some of which will apply to TWiki:Codev.CygWin, and log any issues in TWiki:Codev.WindowsInstallCookbookComments.
Next Steps
See the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the section on basic authentication - remember to use c:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.
See TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache's mod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.
Format of filenames
In your TWiki on Windows installation, it's worth remembering that:
Apache configuration files (e.g. the .htaccess file and c:/apache/conf/httpd.conf) always use Windows format paths, with forward slashes, e.g. c:/twiki
The same is true for the first line of the TWiki Perl scripts (since this line is interpreted by Apache), e.g. c:/cygwin/bin/perl
All other lines in the Perl scripts use Unix format paths, e.g. /twiki (using Cygwin Perl as per this cookbook)
If you are using TWiki:Codev.ActivePerl, that will use Windows format paths, e.g. c:/twiki
Depending on the Perl version used (Cygwin or TWiki:Codev.ActivePerl), the TWiki.cfg file uses a mixture of Unix and Cygwin format paths - stick to the format used in the installation step for TWiki.cfg
RCS always uses Unix format paths, e.g. /twiki
Credits
Material in this cookbook is heavily based on the enormous number of contributions in TWiki:Codev.TWikiOnWindowsArchive and related topics - too many people to thank, but have a look at the contributor list to TWiki:Codev.TWikiOnWindowsArchive to get an idea!
People who've tested or reviewed this document and provided valuable feedback include:
Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003
Overview
This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.
Upgrade Requirements
To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.
To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.
Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
Many more enhancements, see the complete change log at TWikiHistory
Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release
The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Dec-2001 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.
Back up and prepare:
Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates, $TWIKIROOT/lib.
Create a temporary directory and unpack the ZIP file there.
Update files in TWiki root:
Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
Update template files:
Overwrite all template files in $TWIKIROOT/templates with the new ones.
If you have customized your templates, make sure to merge those changes to the new files.
If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files.
Specific changes to templates and skins:
Replace %WIKIHOMEURL% with %WIKILOGOURL%
Replace img tag's src=%PUBURLPATH%/wikiHome.gif with src=%WIKILOGOIMG%
Replace img tag's alt="TWiki Home" with alt="%WIKILOGOALT%"
Replace meta tag's charset=iso-8859-1" with charset=ISO-8859-1"
For internationalized sites, URL encode webs and topics in all form actions, e.g. replace .../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
Update script files:
Overwrite all script files in $TWIKIROOT/bin with the new ones.
If necessary, change the script names to include the required extension, e.g. .cgi
Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
Edit $TWIKIROOT/bin/.htaccess to include a directive for the new manage script: <Files "manage"> require valid-user </Files>
Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
Update library files:
Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one.
Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
Copy and overwrite all subdirectories below $TWIKIROOT/lib with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
Pay attention to the file and directory permissions, the library files should not be executable, e.g. chmod -R 664 $TWIKIROOT/lib/*
Update data files:
Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody.
In case not: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g. www-data:
Change the lock user in the temporary twiki/data/* directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
In the temporary twiki/data/TWiki directory where you unzipped the installation package:
Remove the files you do not want to upgrade: InterWikis.*, TWikiRegistration.*, TWikiRegistrationPub.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
Rename in the temporary directory the file $TWIKIROOT/data/TWiki/TWikiPreferences.* to TWikiPreferencesSave.*.
Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory, overwriting the existing ones.
Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt.
Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory.
Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory (The Test web has been renamed to Sandbox in this release.)
There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki. Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
Adapt the other webs (all other than TWiki and _default):
Merge the new files WebHome.txt and WebPreferences.txt of your other webs to make sure, you have the improvements applied also in your other webs.
Update pub files:
Move all subdirectories below pub/TWiki from your temporary directory into your $TWIKIROOT/pub/TWiki directory.
Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user.
Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory.
Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; fix any potential problems.
Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users.
Test if the installed Plugins work as expected. You should see the list of installed Plugins in TextFormattingRules.
Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.
-- PeterThoeny - 01 Feb 2002
-- MartinRaabe? - 15 Jan 2003
TWiki User Authentication
TWiki site access control and user activity tracking options
TWiki does not authenticate users internally, it depends on the REMOTE_USER environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).
TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.
Authentication Options
No special installation steps are required if the server is already authenticated. If it isn't, you have three standard options for controlling user access:
Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.
Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server.
Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit=, installpasswd, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.
Partial Authentication
Tracking by IP address is an experimental feature, enabled in lib/TWiki.cfg. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:
Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.
TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest.
Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.
This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.
Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:
You are Main.guest
TWiki Username vs. Login Username
This section applies only if your TWiki site is installed on a server that is both authenticated and on an intranet.
TWiki internally manages two usernames: Login Username and TWiki Username.
Login Username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable, and used internally. Login Usernames are maintained by your system administrator.
TWiki Username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the Main web.
TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.
In the original TWiki distribution, in twiki/data, there are two registration form topics, TWikiRegistration and TWikiRegistrationPub?. The original form includes an intranet Login Username field. For Basic Authentication, the original form is replaced by the Pub version. If you started using TWiki on Basic Authentication and want to change, you have to switch back forms for future use, and manually correct the existing entries, by editing TWikiUsers, adding the Login Username for each member - PeterThoeny - pthoeny - 01 Jan 1999 - and also in the .htpasswd file, where you can either replace the WikiNames or duplicate the entries and have both, so both usernames will work. verification and clearer rewrite to follow in a bit. also link to original installation mention.
NOTE:To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Main.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the TWiki.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.
Changing Passwords
Change and reset passwords using forms on regular pages. Use TWikiAccessControl to restrict use as required.
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
Request for reset of password
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will see a page with your new password appearing encrypted.
Restricting read and write access to topics and webs, by Users and groupsTWikiAccessControl allows you restrict access to single topics and entire webs, by individual user and by user Groups, in three areas: view; edit & attach; and rename/move/delete. Access control, combined with TWikiUserAuthentication, lets you easily create and manage an extremely flexible, fine-grained privilege system.
An Important Control Consideration
Open, freeform editing is the essence of WikiCulture - what makes TWiki different and often more effective than other collaboration tools. For that reason, it is strongly recommended that decisions to restrict read or write access to a web or a topic are made with care - the more restrictions, the less Wiki in the mix. Experience shows that unrestricted write access works very well because:
Peer influence is enough to ensure that only relevant content is posted.
Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focussed.
In TWiki, content is transparently preserved under revision control:
Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a collaboration guideline:
Create broad-based Groups (for more and varied input), and...
Avoid creating view-only Users (if you can read it, you should be able to contribute to it).
Users and Groups
Access control is based on the familiar concept of Users and Groups. Users are defined by their WikiNames. They can then be organized in unlimited combinations by inclusion in one or more user Groups. For convenience, Groups can also be included in other Groups.
Managing Users
A user can create an account in TWikiRegistration. The following actions are performed:
WikiName and encrypted password are recorded in .htpasswd if authentication is enabled.
A confirmation e-mail is sent to the user.
A user home page with the WikiName of the user is created in the Main web.
Users can be authenticated using Basic Authentication (htaccess) or SSL (secure server). In either case, TWikiUserAuthentication is required in order to track user identities, and use User and Group access control.
The default visitor name is TWikiGuest. This is the non-authenticated user.
Managing Groups
Groups are defined by group topics created in the Main web, like the TWikiAdminGroup. To create a new group:
EditTWikiGroups by entering a new topic with a name that ends in Group. Example:
SomeGroup
Set Preferences for two Variables in the new group topic:
Set GROUP = < list of Users and/or Groups >
Set ALLOWTOPICCHANGE = < list of Users and/or Groups >
The GROUP variable is a comma-separated list of Users and/or other Groups. Example:
Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
ALLOWTOPICCHANGE defines who is allowed to change the group topic; it is a comma delimited list of Users and Groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. (This prevents Users not in the Group from editing the topic to give themselves or others access. For example, for the TWikiAdminGroup topic write:
Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup
Restricting Write Access
You can define who is allowed to make changes to a web or a topic.
Deny Editing by Topic
Denying editing of a topic also restricts file attachment; both privileges are assigned together.
Define one or both of these variables in a topic, preferably at the end of the page:
Set DENYTOPICCHANGE = < list of Users and Groups >
Set ALLOWTOPICCHANGE = < list of Users and Groups >
DENYTOPICCHANGE defines Users or Groups that are not allowed to make changes to the topic, with a comma-delimited list. Example:
Set DENYTOPICCHANGE = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICCHANGE defines Users or Groups that are allowed to make changes to the topic. It is a comma delimited list of Users and Groups. Example:
Set ALLOWTOPICCHANGE = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICCHANGE is evaluated before ALLOWTOPICCHANGE. Access is denied if the authenticated person is in the DENYTOPICCHANGE list, or not in the ALLOWTOPICCHANGE list. Access is granted in case DENYTOPICCHANGE and ALLOWTOPICCHANGE is not defined.
Deny Editing by Web
Restricting web-level editing blocks creating new topics, changing topics or attaching files.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBCHANGE = < list of Users and Groups >
Set ALLOWWEBCHANGE = < list of Users and Groups >
The same rules apply as for restricting topics, with these additions:
DENYTOPICCHANGE (in topic) overrides DENYWEBCHANGE (in WebPreferences)
ALLOWTOPICCHANGE (in topic) overrides ALLOWWEBCHANGE (in WebPreferences)
Restricting Rename Access
You can define who is allowed to rename, move or delete a topic, or rename a web.
Deny Renaming by Topic
To allow a user to rename, move or delete a topic, they also need write (editing) permission. They also need write access to change references in referring topics.
Define one or both of these variables in a topic, preferably at the end of the topic:
Set DENYTOPICRENAME = < list of Users and Groups >
Set ALLOWTOPICRENAME = < list of Users and Groups >
DENYTOPICCRENAME defines Users or Groups that are not allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
Set DENYTOPICRENAME = Main.SomeBadBoy, Main.SomeBadGirl, Main.SomeHackerGroup
ALLOWTOPICRENAME defines Users or Groups that are allowed to rename the topic. It is a comma delimited list of Users and Groups. Example:
Set ALLOWTOPICRENAME = Main.SomeGoodGuy, Main.SomeGoodGirl, Main.TWikiAdminGroup
DENYTOPICRENAME is evaluated before ALLOWTOPICRENAME. Access is denied if the authenticated person is in the DENYTOPICRENAME list, or not in the ALLOWTOPICRENAME list. Access is granted in case DENYTOPICRENAME and ALLOWTOPICRENAME is not defined.
Deny Renaming by Web
You can define restrictions of who is allowed to rename a TWiki web.
Define one or both of these variable in the WebPreferences topic:
Set DENYWEBRENAME = < list of Users and Groups >
Set ALLOWWEBRENAME = < list of Users and Groups >
The same rules apply as for topics, with these additions:
DENYTOPICRENAME (in topic) overrides DENYWEBRENAME (in WebPreferences)
ALLOWTOPICRENAME (in topic) overrides ALLOWWEBRENAME (in WebPreferences)
Restricting Read Access
You can define who is allowed to see a web.
Deny Viewing by Topic
Technically it is possible to restrict read access to an individual topic based on DENYTOPICVIEW / ALLOWTOPICVIEW preferences variables, provided that the view script is authenticated. However this setup is not recommended since all content is searchable within a web - a search will turn up view restricted topics.
Deny Viewing by Web
You can define restrictions of who is allowed to view a TWiki web. You can restrict access to certain webs to selected Users and Groups, by:
obfuscating webs: Insecure but handy method to hide new webs until content is ready for deployment.
authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.
Obfuscate Webs
The idea is to keep a web hidden by not publishing its URL and by preventing the all webs search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL variable in WebPreferences:
Set NOSEARCHALL = on
This setup can be useful to hide a new web until content its ready for deployment.
Obfuscating webs is insecure, as anyone who knows the URL can access the web.
Authenticate all Webs and Restrict Selected Webs
Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs:
Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
Note:DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
Set NOSEARCHALL = on
Addview to the list of authenticated scripts in the .htaccess file.
This method only works if the view script is authenticated, which means that all Users have to login, even for read-only access. (An open guest account, like TWikiGuest, can get around this, allowing anyone to login to a common account with, for example, view-only access for public webs.) TWikiInstallationGuide has more on Basic Authentication, using the .htaccess file.
Authenticate and Restricting Selected Webs Only
Use the following setup to provide unrestricted viewing access to open webs, with authentication only on selected webs:
Restrict view access to selected Users and Groups. Set one or both of these variables in its WebPreferences topic:
Set DENYWEBVIEW = < list of Users and Groups >
Set ALLOWWEBVIEW = < list of Users and Groups >
Note:DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted in case DENYWEBVIEW and ALLOWWEBVIEW is not defined.
Hide the web from an "all webs" search. Enable this restriction with the NOSEARCHALL variable in its WebPreferences topic:
Set NOSEARCHALL = on
Enable the $doRememberRemoteUser flag in lib/TWiki.cfg as described in TWikiUserAuthentication. TWiki will now remember the IP address of an authenticated user.
Copy the view script to viewauth (or better, create a symbolic link)
Addviewauth to the list of authenticated scripts in the .htaccess file. The view script should not be listed in the .htaccess file.
When a user accesses a web where you enabled view restriction, TWiki will redirect from the view script to the viewauth script once (this happens only if the user has never edited a topic). Doing so will ask for authentication. The viewauth script shows the requested topic if the user could log on and if the user is authorized to see that web.
Authenticating webs is not very secure, as there is a way to circumvent the read access restriction. It can be useful in certain situations - for example, to simplify site organization and clutter, by hiding low traffic webs - but is not recommended for securing sensitive content.
Hiding Control Settings
To hide access control settings from normal browser viewing, place them in comment markers.
<!-- * Set DENYTOPICCHANGE = Main.SomeGroup -->
The SuperAdminGroup
By mistyping a user or group name in the ALLOWTOPICCHANGE setting, it's possible to lock a topic so that no-one can edit it from a browser. To avoid this, you can create Web-based superusers:
Set the $superAdminGroup variable in lib/TWiki.cfg to the name of a group of Users who are always allowed to edit/view topics.
$superAdminGroup = "TWikiAdminGroup";
The default setting is not to have superusers.
-- PeterThoeny - 04 May 2002
-- MikeMannix? - 12 May 2002
TWiki Text Formatting
Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all layed out below - refer back to this page in a pop-up window from the Edit screen.
TWiki Editing Shorthand
Formatting Command:
Example: You write:
You get:
Paragraphs:
Blank lines will create new paragraphs.
1st paragraph
2nd paragraph
1st paragraph
2nd paragraph
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables. Any heading text after !! is excluded from the TOC; for example, write ---+!! text if you do not want to list a header in the TOC.
---++ Sushi
---+++ Maguro
Sushi
Maguro
Bold Text:
Words get bold by enclosing them in * asterisks.
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores.
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
=Fixed font=
Fixed font
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
==Bold fixed==
Bold fixed
Note: Make sure to "stick" the * _ = == signs to the words, that is, take away spaces.
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted. Note: Each tag must be on a line by itself.
Separator:
At least three dashes at the beginning of a line.
-------
List Item:
Three spaces and an asterisk.
* bullet item
bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
* nested stuff
nested stuff
Ordered List:
Three spaces and a number.
1 Sushi
1 Dim Sum
Sushi
Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition. Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the non-breaking-space entity.
Sushi: Japan
Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars. Note:| *bold* | cells are rendered as table headers. Note:| spaced | cells are rendered center aligned. Note:| spaced | cells are rendered right aligned. Note:| 2 colspan || cells are rendered as multi-span columns. Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different TWiki web write Webname.TopicName.
Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (e.g. WikiSyntax) and external link references (e.g. http://TWiki.org/) are supported.
Note: The same Forced Links rules apply for internal link references.
Note: For external link references, you can simply use a space instead of ][ to separate the link URL from the descriptive text.
Note: Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://gnu.org/#Action][GNU Action]].
Anchors:
You can define a link reference inside a TWiki topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
[[WebHome#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS
Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
Note: Each tag must be on a line by itself.
Note: This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing </noautolink> tag (known issue of the TablePlugin).
<noautolink>
RedHat &
SuSE
</noautolink>
RedHat &
SuSE
Mailto: Links:
To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write [[mailto:user@domain descriptive text]].
You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
HTML and TWiki Usability
On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit.
NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
TWiki HTML Rendering
TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
NOTE: The opening and closing angle brackets - <...> - of an HTML tag must be on the same line, or the tag will be broken.
This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, <, ex: a > b
If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
Hyperlinks
Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
Internal Links
GoodStyle is a WikiWord that links to the GoodStyle topic located in the current TWiki web.
NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
External Links
http://..., https://..., ftp://..., gopher://..., news://..., file://..., telnet://...
and mailto:...@... are linked automatically.
Email addresses like name@domain.com are linked automatically.
You can also write [[http://yahoo.com Yahoo home page]] as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.
TWiki Variables
Variables are names that are enclosed in percent signs % that are expanded on the fly.
%TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
%WEB% : The current web, is TWiki.
%TOPIC% : The current topic name, is TextFormattingRules.
%ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif to show the URL of the file or the image in your text.
%INCLUDE{"SomeTopic"}% : Server side include, includes another topic. The current TWiki web is the default web. Example: %INCLUDE{"TWiki.SiteMap"}%
%SEARCH{"sushi"}% : Inline search showing the search result embedded in a topic. FormattedSearch gives you control over formatting, used to create web-based applications.
Plugins provide additional text formatting capabilities and can extend the functionality of TWiki into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.
Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
Check on current Plugin status and settings for this site in TWikiPreferences.
Common Editing Errors
TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ:
Q: Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
A: The '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<' instead of '<', and '>' instead of '>'. Example: Type 'prog <filename>' to get 'prog <filename>'.
Q: Why is the '&' character sometimes not displayed?
-- MikeMannix? - 02 Dec 2001
-- PeterThoeny - 01 Feb 2003
TWiki Variables
Special text strings expand on the fly to display user data or system info
TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. When a topic is rendered for viewing, VARIABLES are replaced by data, either user-entered, or info automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you configure. You can also define custom variables, with new names and values.
Predefined Variables
Most predefined variables return values that were either set in the lib/twiki.cfg file, when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you format the appearance of the display results.
Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.
This version of TWiki - 04 Sep 2004 $Rev: 1742 $ - expands the following variables (enclosed in % percent signs):
Variable:
Expanded to:
%WIKIHOMEURL%
The base script URL of TWiki, is the link of the Home icon in the upper left corner, is http://your.domain.com/twiki
%SCRIPTURL%
The script URL of TWiki, is http://wiki.arch.ethz.ch/caadtwiki/bin
%SCRIPTURLPATH%
The path of the script URL of TWiki, is /caadtwiki/bin
%SCRIPTSUFFIX%
The script suffix, ex: .pl, .cgi is
%PUBURL%
The public URL of TWiki, is http://wiki.arch.ethz.ch/caadtwiki/pub Example: You can refer to a file attached to another topic as %PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
The path of the public URL of TWiki, is /caadtwiki/pub
%ATTACHURL%
The attachment URL of the current topic, is http://wiki.arch.ethz.ch/caadtwiki/pub/TWiki/TWikiVariables Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH%
The path of the attachment URL of the current topic, is /caadtwiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}%
Returns the value of a URL parameter. Note that there is a low risk that this variable could be misused for cross-scripting. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%URLENCODE{"string"}%
Encodes a string for use as a URL parameter. Ex: %URLENCODE{"spaced name"}% returns spaced%20name
%WIKITOOLNAME%
The name of your TWiki site - TWiki
%WIKIVERSION%
Your current TWiki version - 04 Sep 2004 $Rev: 1742 $
%USERNAME%
Your login username - guest
%WIKINAME%
Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME%
Your %WIKINAME% including the Main web name - always use full signatures - Main.guest
The index topic of all registered users - TWikiUsers
%WIKIPREFSTOPIC%
The site-wide preferences topic - TWikiPreferences
%WEBPREFSTOPIC%
The local web preferences topic in each web - WebPreferences
%STATISTICSTOPIC%
The web statistics topic WebStatistics
%TOPIC%
The current topic name - TWikiVariables
%BASETOPIC%
The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE.
%INCLUDINGTOPIC%
The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC%
The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}%
Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
Parameters are format, separator and web:
Format of one line, may include $name and $web variables
"$name"
format="format"
(Alternative to above)
"$name"
separator=", "
line separator
"\n" (new line)
web="Name"
Name of web
Current web
Examples:
%TOPICLIST{" * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}%
Web index, ex: list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
Parameters are format, separator and web:
comma sep list of Web, public expands to all non-hidden
"public"
marker="selected"
Text for $marker where item matches selection, otherwise equals ""
"selected"
selection="%WEB%"
Current value to be selected in list
section="%WEB%"
Examples: %WEBLIST{" * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE%
If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC%
Table of Contents of current topic.
%TOC{"SomeTopic" ...}%
Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC. Parameters are topic name, web and depth:
Search term. Is a regular expression or literal, depending on the regex parameter. For regular expressions ";" is used to mean and e.g. "search;agrep" will find all topic containing search and agrep.
required
search="text"
(Alternative to above)
N/A
web="Name" web="Main Know" web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2]
Current web
scope="topic" scope="text"
Search topic name (title) or in the text (body) of the topic
Custom format results: see FormattedSearch for usage, variables & examples
Results in table
Regular example: %SEARCH{"wiki" web="Main" scope="topic"}%
Formatted example: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"%(displays results in a table with header - details) If the TWiki:Plugins.TablePlugin is installed, you may set a %TABLE{}% variable just before the %SEARCH{}% to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children
required
web="%WEB%"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs.
required
topic="%TOPIC%"
The topic the search relates to
required
title="Title"
Text that is prepended to any search results
required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}%
Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0
[1] Note: The search form uses identical names for input fields.
[2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences.
Preferences Variables
Additional variables are defined in the preferences ( site-level ( SL ) in TWikiPreferences, web-level ( WL ) in WebPreferences of each web, and user level ( UL ) preferences in individual user topics):
Variable:
Level:
What:
%WIKIWEBMASTER%
SL
Webmaster email address (sender of email notifications) , is caad-yearly@hbt.arch.ethz.ch
%WIKIWEBLIST%
SL
List of TWiki webs (in upper right corner of topics)
%WEBTOPICLIST%
WL
Common links of web (second line of topics)
%WEBCOPYRIGHT%
SL , WL
Copyright notice (bottom right corner of topics)
%WEBBGCOLOR%
WL
Background color of web
%NOSEARCHALL%
WL
Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR%
SL , UL
Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR%
SL , UL
Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH%
SL , UL
Horizontal size of edit box, is 70
%EDITBOXHEIGHT%
SL , UL
Vertical size of edit box, is 15
%RELEASEEDITLOCKCHECKBOX%
SL , UL
Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is: checked
%DONTNOTIFYCHECKBOX%
SL , UL
Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty. Value is: checked
%ATTACHLINKBOX%
SL , UL
Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is:
%HTTP_EQUIV_ON_VIEW%
SL
http-equiv meta tags for view, rdiff, attach, search* scripts.
%HTTP_EQUIV_ON_EDIT%
SL , UL
http-equiv meta tags for edit script.
%HTTP_EQUIV_ON_PREVIEW%
SL , UL
http-equiv meta tags for preview script.
%DENYWEBCHANGE%
WL
List of users and groups who are not allowed to change topics in the TWiki web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE%
WL
List of users and groups who are allowed to change topics in the TWiki web. (More in TWikiAccessControl)
%DENYTOPICCHANGE%
(any topic)
List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE%
(any topic)
List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME%
WL
List of users and groups who are not allowed to rename topics in the TWiki web. (More in TWikiAccessControl)
%ALLOWWEBRENAME%
WL
List of users and groups who are allowed to rename topics in the TWiki web. (More in TWikiAccessControl)
%DENYTOPICRENAME%
(any topic)
List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME%
(any topic)
List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES%
SL , WL
List of preferences that are not allowed to be overridden by next level preferences
Note: There are some more useful variables defined in the TWikiPreferences like %BR% for line break, colors like %RED% for colored text and small icons like %H% for a Help icon.
Setting Preferences
The syntax for Preferences Variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): [multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [value] Examples:
Set VARIABLENAME = value
Set VARIABLENAME = value
Creating Custom Variables
You can add your own Preference Variables for us across an entire site or a single web, using the standard Preferences syntax. Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly. You can place formatted text, page links, image paths.
Example: Create a custom logo variable the TWiki web
To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences page, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, ex: LogoTopic:
Set MYLOGO = %PUBURL%/TWiki/LogoTopic/mylogo.gif
-- PeterThoeny - 19 Jan 2003
-- MikeMannix? - 12 May 2002
File Attachments
Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved.
What Are Attachments Good For?
File Attachments can be used to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.
Document Management System
You can use Attachments to store and retrieve documents (in any format, with associated graphics, and other media files); attach documents to specific TWiki topics; collaborate on documents with full revision control; distribute documents on a need-to-know basis using web and topic-level access control; create a central reference library that's easy to share with an user group spread around the world.
File Sharing
For file sharing, FileAttachments on a series of topics can be used to quickly create a well-documented, categorized digital download center for all types of files: documents; graphics and other media; drivers and patches; applications; anything you can safely upload!
Web Authoring
Through your Web browser, you can easily upload graphics (or sound files, or anything else you want to link to on a page) and place them on a single page, or use them across a web, or site-wide.
NOTE: You can also add graphics - any files - directly, typically by FTP upload. This requires FTP access, and may be more convenient if you have a large number of files to load. FTP-ed files can't be managed using browser-based Attachment controls. You can use your browser to create TWikiVariables shortcuts, like this %H% = .
Uploading Files
Click on the Attach link at the bottom of the page. The Attach screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the File Attachment table.
Any type of file can be uploaded. Some files that might pose a security risk are renamed, ex: *.php files are renamed to *.php.txt so that no one can place code that would be read in a .php file.
The previous upload path is retained for convenience. In case you make some changes to the local file and want to upload it, again you can copy the previous upload path into the Local file field.
Currently there is no file size limit other than the disk space on the server.
* It's not recommended to upload files greater than a few hundred K through a browser. Large files can be extremely slow-loading, and often time out. Use FTP for large file uploads.
NOTE: There is no access control on individual attachments. If you need control over single files, create a separate topic per file and set topic-level access restrictions for each.
Moving Attachment Files
An attachment can be moved between topics.
Click Action on the Attachment to be moved.
On the control screen, select the new web and/or topic.
Click Move. The attachment and its version history are moved. The original location is stored as topic Meta Data.
Deleting Attachments
It is not possible to delete attached files directly. You can delete a topic, and its attachments with it.
One easy workaround is to create a Trash.TrashAttachments - then, simply move unwanted Attachments to that topic.
Linking to Attached Files
Once a file is attached it can be referenced in the topic. Example:
GIF, JPG and PNG images can be attached and shown embedded in a topic. Example:
Attach file: Smile.gif
Edit topic and write text: %ATTACHURL%/Smile.gif
Preview: text appears as , an image.
File Attachment Contents Table
Files attached to a topic are displayed in a directory table, displayed at the bottom of the page, or optionally, hidden and accessed when you click Attach.
Clicking on an Action link takes you to a new page that looks like this:
The first table is a list of all attachments, including their attributes. An h means the attachment is hidden, it isn't listed when viewing a topic.
The second table is all the versions of the attachment. Click on View to see that version. If it's the most recent version, you'll be taken to an URL that always displays the latest version, which is usually what you want.
To change the comment on an attachment, enter a new comment and then click Change properties. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
To hide/unhide an attachment, enable the Hide file checkbox, then click Change properties.
Known Issues
Unlike topics, attachments are not locked during editing. As a workaround, you can change the comment to indicate an attachment file is being worked on - the comment on the specific version isn't lost, it's there when you list all versions of the attachment.
TWiki Forms
Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web & topic
Overview
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.
Form Templates replace TWikiCategoryTables from the 01-Dec-2000 version of TWiki.
Main Changes from Category Tables
The Form Template system is a more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.
Defining a Form Template
A Form Template is simply a page containing your form, defined as a table where each row is one form field.
Form Template Elements
form template - a set of fields defining a form (replaces category table definition)
A web can use one or more form templates
form - a topic containing additional meta data (besides the freeform TEXTAREA) that categorizes the content (replaces category table)
Within a form-enabled web, individual topics can have a form or no form
form field - a named item in a form (replaces category item name)
field type - selects the INPUT type:
select - drop-down menu or scrollable box
checkbox - one or more checkboxes
checkbox+buttons - one or more checkboxes, plus Set and Clear buttons
radio - one or more radio buttons
text - a one-line text field
textarea - a text box; size is 40x10 (columns x rows)
field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces category item value)
Defining a Form in One Topic
Create a new topic with your form name: YourForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, and Tooltip message(see sample below).
For each field, fill in a new line; for the type of field, select from the list.
Save the topic (you can later choose to enable/disable individual forms).
Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
Topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists.
[[...]] links can be used to force a link (at present, the [[...][...]] format is not supported).
The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip In edit.
The first item in the list is the default item. Alternative initial values can be set in a topic template, like WebTopicEditTemplate, with field=value, or, for checkboxes, field=1.
The topic definition is not read when a topic is viewed.
Enabling Forms by Web
Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates. Example:
Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.
Including Forms in New Topics
A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.
Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:
other than checkboxes: name, ex: ?BugPriority=1
checkbox: namevalue=1, ex: ?ColourRed=1.
Boxes with a tick must be specified.
Setting Up Multiple Form Options
The optional WEBFORMS variable defines alternative forms that can be selected by pressing Change in edit mode.
A topic template can use any form.
New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form.
Form Data Storage
The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.
Using Form Data
TWikiForms accept user-input data, stored as TWikiMetaData. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see TWikiMetaData, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search for various options.
-- JohnTalintyre - 16 Aug 2001
-- MikeMannix? - 05 Jan 2002
TWiki Templates
Definition of the templates used to render all HTML pages displayed in TWiki
Overview
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.
Major changes from the previous template system
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
separates a set of common template parts into a base template that is included by all of the related templates;
defines common variables, like a standard separator (ex: "|"), in the base template;
defines variable text in the individual templates and passes it back to the base template.
How Template Variables Work
Special template directives (or preprocessor commands) are embedded in normal templates.
All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
Directives:
%TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
%TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
%TMPL:END%: Ends variable definition.
%TMPL:P{"var"}%: Prints a previously defined variable.
Variables live in a global name space: there is no parameter passing.
Two-pass processing lets you use a variable before or after declaring it.
Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
Use of template directives is optional: templates work without them.
NOTE: Template directives work only for templates: they do not get processed in topic text.
Types of Template
There are three types of template:
Master Template: Stores common parts; included by other templates
HTML Page Templates: Defines the layout of TWiki pages
Template Topics: Defines default text when you create a new topic
Master Templates
Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: twiki.tmpl is the default master template.
Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%
Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}%
Skeleton of oops dialog
HTML Page Templates
TWiki uses HTML template files for all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.
Templates are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:
twiki/templates/$webName/$scriptName.tmpl
twiki/templates/$scriptName.tmpl
$webName is the name of the web (ex: Main)
$scriptName is the script (ex: view).
NOTE:TWikiSkins can be defined to overload the standard templates.
Special variables are used in templates, especially in view, to display meta data.
Template Topics
Template topics define the default text for new topics. There are three types of template topic:
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
A topic name specified by the templatetopic CGI parameter.
WebTopicEditTemplate in the current web
WebTopicEditTemplate in the TWiki web
Edit Template Topics and Variable Expansion
The following variables get expanded when a user creates a new topic based on a template topic:
A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}%
%NOP{ ... }%
A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example: %NOP{ * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup }%
Notes:
Unlike other variables, %NOP{ ... }% can span multiple lines.
The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%: Insert a %NOP% between } and %. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
Template Topics in Action
Here is an example for creating new topics based on a specific template topic:
The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="submit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
The onlywikiname parameter enforces WikiWords for topic names.
TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: -- %WIKIUSERNAME% - %DATE%
Templates by Example
Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.
Base template oopsbase.tmpl
The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%
Each oops template basically just defines some variables and includes the base template that does the layout work.
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
* Some more blah blah blah blah blah blah blah blah blah blah...
* Param1: %PARAM1%
* Param2: %PARAM2%
* Param3: %PARAM3%
* Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%
Sample screen shot of oopstest.tmpl
With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
Known Issues
A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a .tmpl filename extension - it contained unresolved %VARIABLES%, but could still be previewed directly in a browser.
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
Overview
Skins are customized TWikiTemplates files. You can use skins to change the look of a TWiki topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.
Defining Skins
Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.
Use the existing TWikiTemplates (like view.tmpl) or skin files as a base for your own skin, name it for example view.myskin.tmpl.
Variables in Skins
You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:
Web specific background color, defined in the WebPreferences
%WIKITOOLNAME%
The name of your TWiki site
%SCRIPTURL%
The script URL of TWiki
%SCRIPTSUFFIX%
The script suffix, ex: .pl, .cgi
%WEB%
The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment
%TOPIC%
The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment
%WEBTOPICLIST%
Common links of current web, defined in the WebPreferences. It includes a #GoBox
%TEXT%
The topic text, e.g. the content that can be edited
The %WEBTOPICLIST% includes a "Go" box to jump to a topic. The box also understand URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:
The ?skin=name URL parameter overrides the SKIN Preference value.
-- PeterThoeny - 05 Jan 2003
TWiki Formatted Search Results
Inline search feature allows flexible formatting of search result
The %SEARCH{...}% variable documented in TWikiVariables has a fixed format for the search result, that is, a table consisting of topic names and topic summaries. Use the format="..." parameter to specify a customized format of the search result. The string of the format parameter is typically a bullet list or table row containing variables (such as %SEARCH{ "food" format="| $topic | $summary |" }%).
Syntax
Two parameters can be used to specify a customized search result:
1. header="..." parameter
Use the header parameter to specify the header of a search result. It should correspond to the format of the format parameter. This parameter is optional. Example: header="| *Topic:* | *Summary:* |"
2. format="..." parameter
Use the format parameter to specify the format of one search hit.
Example: format="| $topic | $summary |"
Variables that can be used in the format string:
Topic name, hyphenated each 30 characters with separator "-<br />"
$topic(40, ...)
Topic name, shortended to 40 characters with "..." indication
$text
Formatted topic text
$locked
LOCKED flag (if any)
$date
Time stamp of last topic update, like 08 May 2009 - 00:57
$isodate
Time stamp of last topic update, like 2009-05-08T00:57Z
$rev
Number of last topic revision, like 1.4
$wikiusername
Wiki user name of last topic update, like Main.JohnSmith
$username
User name of last topic update, like JohnSmith
$summary
Topic summary
$formfield(name)
The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ. This applies only to topics that have a TWikiForm
$formfield(name, 10)
Form field value, "- " hyphenated each 10 characters
$formfield(name, 20, -<br />)
Form field value, hyphenated each 20 characters with separator "-<br />"
$formfield(name, 30, ...)
Form field value, shortended to 30 characters with "..." indication
$pattern(reg-exp)
A regular expression pattern to extract some text from a topic. For example, $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the email address from a bullet of format * Email: ....
$n or $n()
New line
$nop or $nop()
Is a "no operation". This variable gets removed; useful for nested search
$quot
Double quote ("). Alternatively write \" to escape it
$percnt
Percent sign (%)
$dollar
Dollar sign ($)
Note: For $pattern(reg-exp), specify a RegularExpression that scans from start to end and contains the text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*). You need to make sure that the integrity of a web page is not compromised; for example, if you include a table make sure to include everything including the table end tag.
TWikiFAQ: Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TWikiFaqTemplate: FAQ: Answer: Back to: NOP TWikiFAQ WIKIUSERNAME DATE
TextFormattingFAQ: Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
Table showing form field values of topics with a form
Write this in the Know web:| *Topic:* | *OperatingSystem:* | *OsVersion:* | %SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" regex="on" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%To get this:
Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer...
Nested Search
Search can be nested. For example, search for some topics, then form a new search for each topic found in the first search. The idea is to build the nested search string using a formatted search in the first search.
Here is an example. Let's search for all topics that contain the word "culture" (first search), and let's find out where each topic found is linked from (second search).
First search:
%SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
Second search. For each hit we want this search:
%SEARCH{ "(topic found in first search)" format=" $topic" nosearch="on" nototal="on" }%
Now let's nest the two. We need to escape the second search, e.g. the first search will build a valid second search string. Note that we escape the second search so that it does not get evaluated prematurely by the first search:
Use $percnt to escape the leading percent of the second search
Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs
Overview
TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
Meta Data Syntax
Format is the same as in TWikiVariables, except all fields have a key.
%META:<type>{key1="value1" key2="value2" ...}%
Order of fields within the meta variables is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the variables themselves is defined).
Each meta variable is on one line.
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Meta Data Specifications
The current version of Meta Data is 1.0, with support for the following variables.
Format of this topic, will be used for automatic format conversion
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed.
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
form fields remain in the order they are defined
the diff function output appears in a logical order
The recommended sequence is:
META:TOPICINFO
text of topic
META:TOPICMOVED (optional)
META:TOPICPARENT (optional)
META:FILEATTACHMENT (0 or more entries)
META:FORM (optional)
META:FIELD (0 or more entries; FORM required)
Viewing Meta Data in Page Source
When viewing a topic the Raw Text link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic
Rendering Meta Data
Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.
Current support covers:
Show attachments, except for hidden ones. Options: all="on": Show all attachments, including hidden ones.
%META{"moved"}%
Details of any topic moves.
%META{"parent"}%
Show topic parent. Options: dontrecurse="on": By default recurses up tree, at some cost. nowebhome="on": Suppress WebHome. prefix="...": Prefix for parents, only if there are parents, default "". suffix="...": Suffix, only appears if there are parents, default "". separator="...": Separator between parents, default is " > ".
Known Issues
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.
-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001
-- PeterThoeny - 10 Jan 2002
TWiki Plugins
Plug-in enhanced feature add-ons, with a Plugin API for developers
Overview
You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:
add virtually unlimited features while keeping the main TWiki code compact and efficient;
heavily customize an installation and still do clean updates to new versions of TWiki;
rapidly develop new TWiki functions in Perl using the Plugin API.
Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.
Preinstalled Plugins
TWiki comes with three Plugins as part of the standard installation.
DefaultPlugin optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)
EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.
InterwikiPlugin is preinstalled but can be disabled or removed. Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own.
Installing Plugins
Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.
Most Plugins can be installed in three easy steps, with no programming skills required:
Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
Check the demo example on the Plugin topic: if it's working, the installation was fine!
Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.
Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.
Doc page: Read all available info about the Plugin; download the attached distribution files.
Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.
On-Site Pretesting
To test new Plugins on your installation before making them public, you may want to use one of these two approaches:
Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
Test Plugins and other new features in the Test installation until you're satisfied.
If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.
Method 2: List the Plugin being tested in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Sandbox web and do the testing there.
Managing Plugins
When you finish installing a Plugin, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.
Setting Preferences
Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
All Plugin modules present in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the TWiki web for the Plugin topics. Settings in TWikiPreferences are:
Set INSTALLEDPLUGINS = DefaultPlugin, ...
Set DISABLEDPLUGINS = EmptyPlugin, ...
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
Set SHORTDESCRIPTION = Blah blah woof woof.
Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
Set DEBUG = 0
The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
Listing Active Plugins
Plugin status variables let you list all active Plugins wherever needed. There are two list formats:
The %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.
DEMO: Automatically List Active Plugins Using Variables
Using %ACTIVATEDPLUGINS%:
On this TWiki site, the active Plugins are: DefaultPlugin, EditTablePlugin, InterwikiPlugin, TablePlugin.
Using %PLUGINDESCRIPTIONS%:
You can use any of these active TWiki Plugins:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
The TWiki Plugin API
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
Available Core Functions
The TWikiFuncModule (lib/TWiki/Func.pm) implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
If you use functions not in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
Predefined Hooks
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.
For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.
Plugin Version Detection
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
All modules require a $VERSION='0.000' variable, beginning at 1.000.
The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).
With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API Plugins by providing a programming interface for TWiki.
The DefaultPlugin Alternative
DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.
Anatomy of a Plugin
A basic TWiki Plugin consists of two elements:
a Perl module, ex: MyFirstPlugin.pm
a documentation topic, ex: MyFirstPlugin.txt
The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call.
In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop Plugins.
Creating the Perl Module
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. The EmptyPlugin.pm module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write Package MyFirstPlugin::Attrs; instead of just Package Attrs;. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs;
$var = MyFirstPlugin::Attrs->new();
Writing the Documentation Topic
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic:
OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:
Syntax Rules: <Describe any special text formatting that will be rendered.>"
Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"
Plugin Global Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
Set <EXAMPLE = value added>
Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"
Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Packaging for Distribution
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
Publishing for Public Use
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
Post the Plugin documentation topic in the TWiki:Plugins web:
create a new topic using the Plugin name, ex: MyFirstPlugin.txt
Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
Official list of stable TWiki functions for Plugin developers
Description
This module defines official funtions that Plugins and add-on
scripts can use to interact with the TWiki engine and content.
Plugins should only use functions published in this module. If you use
functions in other TWiki libraries you might impose a security hole and
you will likely need to change your Plugin when you upgrade TWiki.
Functions: CGI Environment
getSessionValue( $key ) ==> $value
Description:
Get a session value from the Session Plugin (if installed)
Parameter: $key
Session key
Return: $value
Value associated with key; empty string if not set; undef if session plugin is not installed
setSessionValue( $key, $value ) ==> $result
Description:
Set a session value via the Session Plugin (if installed)
Parameter: $key
Session key
Parameter: $value
Value associated with key
Return: $result
"1" if success; undef if session plugin is not installed
getSkin( ) ==> $skin
Description:
Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter
Return: $skin
Name of skin, e.g. "gnu". Empty string if none
getUrlHost( ) ==> $host
Description:
Get protocol, domain and optional port of script URL
Return: $host
URL host, e.g. "http://example.com:80"
getScriptUrl( $web, $topic, $script ) ==> $url
Description:
Compose fully qualified URL
Parameter: $web
Web name, e.g. "Main"
Parameter: $topic
Topic name, e.g. "WebNotify"
Parameter: $script
Script name, e.g. "view"
Return: $url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
getScriptUrlPath( ) ==> $path
Description:
Get script URL path
Return: $path
URL path of TWiki scripts, e.g. "/cgi-bin"
getViewUrl( $web, $topic ) ==> $url
Description:
Compose fully qualified view URL
Parameter: $web
Web name, e.g. "Main". The current web is taken if empty
Parameter: $topic
Topic name, e.g. "WebNotify"
Return: $url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
First extract text between {...} to get: "nameless" name1="val1" name2="val2"
Then call this on the text: my $noname = TWiki::Func::extractNameValuePair( $text ); my $name1 = TWiki::Func::extractNameValuePair( $text, "name1" ); my $name2 = TWiki::Func::extractNameValuePair( $text, "name2" );
getPreferencesValue( $key, $web ) ==> $value
Description:
Get a preferences value from TWiki or from a Plugin
Parameter: $key
Preferences key
Parameter: $web
Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value
Preferences value; empty string if not set
Example for Plugin setting:
MyPlugin topic has: * Set COLOR = red
Use "MYPLUGIN_COLOR" for $key
my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
Example for preferences setting:
WebPreferences topic has: * Set WEBBGCOLOR = #FFFFC0
my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );
getPreferencesFlag( $key, $web ) ==> $value
Description:
Get a preferences flag from TWiki or from a Plugin
Parameter: $key
Preferences key
Parameter: $web
Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value
Preferences flag "1" (if set), or "0" (for preferences values "off", "no" and "0")
Example for Plugin setting:
MyPlugin topic has: * Set SHOWHELP = off
Use "MYPLUGIN_SHOWHELP" for $key
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
getWikiToolName( ) ==> $name
Description:
Get toolname as defined in TWiki.cfg
Return: $name
Name of tool, e.g. "TWiki"
getMainWebname( ) ==> $name
Description:
Get name of Main web as defined in TWiki.cfg
Return: $name
Name, e.g. "Main"
getTwikiWebname( ) ==> $name
Description:
Get name of TWiki documentation web as defined in TWiki.cfg
Return: $name
Name, e.g. "TWiki"
Functions: User Handling and Access Control
getDefaultUserName( ) ==> $loginName
Description:
Get default user name as defined in TWiki.cfg's $defaultUserName
Return: $loginName
Default user name, e.g. "guest"
getWikiName( ) ==> $wikiName
Description:
Get Wiki name of logged in user
Return: $wikiName
Wiki Name, e.g. "JohnDoe"
getWikiUserName( $text ) ==> $wikiName
Description:
Get Wiki name of logged in user with web prefix
Return: $wikiName
Wiki Name, e.g. "Main.JohnDoe"
wikiToUserName( $wikiName ) ==> $loginName
Description:
Translate a Wiki name to a login name based on Main.TWikiUsers topic
The $oopsUrl for calling redirectCgiQuery(), user's $loginName, and estimated $unlockTime in minutes. The $oopsUrl and $loginName is empty if topic has no edit lock.
Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.
Parameter: $web
Web name, e.g. "Main", or empty
Parameter: $topic
Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $text
Topic text to save, assumed to include meta data
Parameter: $ignorePermissions
Set to "1" if checkAccessPermission() is already performed and OK
Parameter: $dontNotify
Set to "1" if not to notify users of the change
Return: $oopsUrl
Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error
Example: my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 ); if( $oopsUrl ) { TWiki::Func::redirectCgiQuery( $query, $oopsUrl ); # assuming valid query return; } my $text = TWiki::Func::readTopicText( $web, $topic ); # read topic text # check for oops URL in case of error: if( $text =~ /^http.*?\/oops/ ) { TWiki::Func::redirectCgiQuery( $query, $text ); return; } # do topic text manipulation like: $text =~ s/old/new/g; # do meta data manipulation like: $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/; $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text TWiki::Func::setTopicEditLock( $web, $topic, 0 ); # unlock topic if( $oopsUrl ) { TWiki::Func::redirectCgiQuery( $query, $oopsUrl ); return; }
getPublicWebList( ) ==> @webs
Description:
Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences
Return: @webs
List of all public webs, e.g. ( "Main", "Know", "TWiki" )
getTopicList( $web ) ==> @topics
Description:
Get list of all topics in a web
Parameter: $web
Web name, required, e.g. "Sandbox"
Return: @topics
Topic list, e.g. ( "WebChanges", "WebHome", "WebIndex", "WebNotify" )
Format type, optional. Default e.g. "31 Dec 2002 - 19:30", can be "iso" (e.g. "2002-12-31T19:30Z"), "rcs" (e.g. "2001/12/31 23:59:59", "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT")
Return: $text
Formatted time string
Functions: File I/O
getDataDir( ) ==> $dir
Description:
Get data directory (topic file root)
Return: $dir
Data directory, e.g. "/twiki/data"
getPubDir( ) ==> $dir
Description:
Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName
Read text file, low level. NOTE: For topics use readTopicText()
Parameter: $filename
Full path name of file
Return: $text
Content of file
saveFile( $filename, $text )
Description:
Save text file, low level. NOTE: For topics use saveTopicText()
Parameter: $filename
Full path name of file
Parameter: $text
Text to save
Return:
none
writeWarning( $text )
Description:
Log Warning that may require admin intervention to data/warning.txt
Parameter: $text
Text to write; timestamp gets added
Return:
none
writeDebug( $text )
Description:
Log debug message to data/debug.txt
Parameter: $text
Text to write; timestamp gets added
Return:
none
Copyright and License
Copyright (C) 2000-2003 Peter Thoeny, Peter@Thoeny.com
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details, published at
http://www.gnu.org/copyleft/gpl.htmlNOTE: Above text is copied from the TWiki::Plugins/PerlDocPlugin output of TWiki::Func in twiki format. In case you want to get dynamically updated documentation based on the actual Perl module, install the PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.
-- PeterThoeny - 31 Dec 2002
TWiki Site Tools
Utilities for searching, navigation, and monitoring site activityTWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to email alerts when topics are edited, and WebStats, to generate detailed activity reports.
WebNotify Recent Changes Alert
Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a background process at regular intervals. The script sends an automated email to subscribed users if topics were changed in a web since the script was last run.
The first entry is the default form, the notification gets sent to the e-mail address specified in the user's home page. The second entry lists an alternative e-mail address. The third entry specifies a group, the notification gets sent to each member of the group.
You can also use %MAINWEB% instead of Main, but this is not necessary even if you have renamed the main web by configuring $mainWebname in TWiki.cfg.
Configuring Outgoing Mail
TWiki will use the Net::SMTP module if it is installed on your system. Set this with the SMTPMAILHOST variable in TWikiPreferences.
The notify e-mail uses the default changes.tmpl template, or a skin if activated in the TWikiPreferences.
mailnotify also relies on two hidden files in each TWiki/data/[web] directory: .changes and .mailnotify. Make sure both are writable by your web server process. .changes contains a list of changes; go ahead and make this empty. .mailnotify contains a timestamp of the last time notification was done.
You can use an external mail program, like sendmail, if the Net::SMTP module is not installed. Set the program path in $mailProgram in TWiki.cfg.
Net::SMTP can be easily disabled (ex: if there is an installation error) by setting SMTPMAILHOST in TWikiPreferences to an empty value.
You can set a separate SMTPSENDERHOST variable to define the mail sender host (some SMTP installations require this).
Setting the Automatic Email Schedule
For Unix platforms: Edit the cron table so that mailnotify is called in an interval of your choice. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:
The above line will call mailnotify at 15 minutes and 45 minutes past every hour. The -q switch suppresses all normal output.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows NT/2000: You can use a scheduled task if you have administrative privileges.
Note: AT on an NT machine is pretty limited.
Microsoft lists several third-party
replacements
(as of 2001-11-20, none of them free).
WebStatistics Site Usage Log
You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.
You can automatically generate usage statistics for all webs. To enable this:
Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in TWiki.cfg are set. This will generate log entries in file twiki/data/log<date>.txt .
The WebStatistics topic must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry: 0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example: 0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
Generating Statistics Manually by URL
The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
Update current month for all webs: http://mydomain.com/twiki/bin/statistics
Update current month for Main web only: http://mydomain.com/twiki/bin/statistics/Main
Update January 2000 for Main web: http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
WebSearch
WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:
topic title or full-text search
regular expressions
search within web or site-wide
index-style A-Z alphabetical listing sorted topic title
many more
See also: TWikiVariables for including hard-coded searches in text.
WebChanges
To check for the most recently edited topics while on-site, use the WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.
This is simply a preset SEARCH. The number of topics listed by the limit parameter.:
-- MikeMannix? - 01 Dec 2001
-- PeterThoeny - 30 Jan 2003
Managing Topics
Browser-based rename, move, and delete for individual topics
Overview
You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden Trash web.
How to Rename/Move/Delete a Topic
Click on [More] (bottom right of page) on the topic to be changed, then, in the new screen, on [Rename/move]. You can now rename and/or move/delete in one operation:
Move/Delete: Select the target web if other than the current web - choose Trash to delete a topic.
Rename: Enter the new topic name - default is current name NOTE: You'll be warned if any of the topics to be affected are locked (being edited), or if there is a name conflict.
Prevent updates by unchecking individual items on the list of referring links - these topics will NOT to be updated with the new name (by default, all referring links will be updated).
Click on [Rename/Move]: the topic will be renamed and links to the topic updated as requested.
If any of the referring pages are locked then they will be listed: you can correct these later by again pressing [Rename/Move].
There is a Put back feature that allows you to undo a Rename/Move/Delete - an instruction line and undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.
Deleted Topics: How to Clear the Trash
Deleted topics are moved to a special Trash web - they are NOT physically erased from the server. All webs share Trash - in case of a name conflict with a topic already Trash, the user is alerted and asked to choose a new name.
The Trash web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the Trash directory.
This can only be done from on the server, not through the browser.
Since simple FTP access to the Trash directory is all that's required for maintenance, it's possible to grant Trash admin privileges to multiple users, while strictly limiting server access.
Redirecting from an Old Topic
You can use TWikiMetaData to place a command in the WebTopicViewTemplate and WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED{...}%. Customize something like this:
%<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%"
title="This topic used to exist and was moved to: "}%
How Rename/Move Works
%SEARCH%, with a special template, finds and displays all occurrences of the topic name in other topics, site-wide. These referring links are by default automatically changed to the new topic and/or web name. This includes relevant TWikiMetaData definitions.
User can omit one or more topics from the update list by unchecking them.
<pre> and <verbatim> are honoured - no changes are made to text within these areas.
The topic is moved (if locks allow).
References are changed (locks and permissions permitting).
Any referring topics that can't be changed due to locks are listed - user can take note and change them at another time.
How Referring Topics Are Found
Referring topics are found using the %SEARCH% variable - see the template searchrenameview.tmpl. First, matching topics in the current web are listed - matches are to topic. Next, all webs (including the current one) are listed that match web.topic. Because %SEARCH% is used, webs marked in WebPreferences as NOSEARCHALL will not show up in the search for references to the topic being changed.
Changed references are kept are as short as possible, ex: topic is used in preference to web.topic.
Effect of User Access Settings
User permissions affect the Rename function in various ways. To rename a topic, you need both ALLOWTOPICCHANGE and ALLOWTOPICRENAME permission for that topic. To alter referring topics, you need change permission. See TWikiAccessControl for information on setting up access permissions.
Special Considerations
Consider carefully whether to make browser-based Rename/Move/Delete widely available, or to restrict it to an administrator/moderator group. Allowing all users to easily manipulate topics can be extremely useful in refactoring a busy web or site. However, there are at least two significant potential drawbacks to take into account:
When referring links are updated, the modified topics appear in WebChanges, creating the impression that editorial changes were made. This can undermine the usefulness of WebChanges.
Due to current limitations, fairly heavy use of Rename/Move/Delete functions can lead to an accumulation of minor technical problems (ex: broken links) and usability issues (ex: user confusion). If Rename... is used heavily, these negatives will obviously increase, in number and effect.
Ultimately, the size, objectives, and policies of your TWiki site, the real-world behavior of your user group, and most importantly, the initial TWiki site management leadership, will determine the most effective implementation of this feature, and the success of the site overall.
Known Issues
Rename/Move is fairly complicated due to the dynamic generation of links. Ideally, it would be possible to run the required part of rendering in a way that would allow identification of the text to be changed. Unfortunately, these hooks don't exist in TWiki at present. Instead, %SEARCH% is used with a special template to show the text to be changed, and the selected topics are then altered. One drawback is that search can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]]
[[old topic]] => [[NewTopic][old topic]]
[[old t opic]] => not changed
[[OldTopic]] => [[NewTopic]]
Adding webs is a web based operation; renaming and deleting webs are manual operations done directly on the server
Overview
A TWikiSite is divided into webs; each one represents one subject, one area of collaboration. Administrators can add/rename/delete webs.
Choose Web Template
There are two methods used to create a new web. First you can use a specially designed TemplateWeb. This is an invisible web that begins with an underscore "_" character. All topics in the _default template web will be copied into your new web.
The second method is to use an existing web as a template web. This may be useful if you already have a web that you like to use as a starting point. Only topics that have names beginning with Web... (like "WebHome", "WebNotify", etc.) are copied.
In either case you will want to be sure to verify that your new web has all the custom modifications that you desire.
Adding a New Web
Note: Attachments will NOT get copied over along with their topics. This will be a feature added for the TWiki:Codev/CairoRelease.
Note: This script does not yet edit the TWiki.TWikiPreferences file to update the WIKIWEBLIST. This must be done by hand.
The manage script while creating the new web will update the following variables in the WebPreferences: WEBBGCOLOR, SITEMAPLIST, SITEMAPWHAT, SITEMAPUSETO and NOSEARCHALL. These variables are now used to dynamically generate the SiteMap.
Renaming or Deleting a Web
Renaming or deleting a web requires direct access to the installation files on the host server. There are currently no browser-based equivalents of the Rename/move/delete topic tools for working with webs.
NOTE: If you plan to rename the TWiki.Main web, remember that TWiki stores user and group topics in %MAINWEB%, default named Main. That means, every WikiName signature - Main.SomeUserName - points to it and would need updating (unless the variable, %MAINWEB%.SomeUserName, is used throughout).
Prepare your site: Search each web for links to the target web, searching topic text for Oldwebname., including the dot so you'll find references like Oldwebname.SomeTopic.
Make changes as required, to Newwebname.SomeTopic or better yet, to %MAINWEB%.SomeTopic.
Edit the TWikiPreferences topic: Rename or delete the web from the WIKIWEBLIST variable.
Login to the TWiki server, via Telnet or FTP.
Go to twiki/data and rename or remove the web directory.
Go to twiki/templates and rename or remove the web directory if present.
Go to twiki/pub and rename or remove the web directory if present.
Annotated directory and file listings, for the 01-Feb-2003 TWiki production release.
Who and What is This Good For?
Interested Users and Site Administrators can find out in simple terms what each part of TWiki actually does. Adventurous Adminstrators with server access to files (via telnet, ssh or ftp) can also figure out where to look to make minor modifications, like changing hardcode text or color. Software Developers can get an at-a-glance overview of TWiki code architecture.
Directory Structure
You can rename the root TWiki directory - twiki - to whatever you like by changing it in the TWiki.cfg configuration file. However, to keep the current installation and future upgrades simple, you should leave the five main subdirectories intact:
Back-end storage, *.txt text file and *.txt,v RCS repository file handling
TWiki/Store/RcsFile.pm
Generic file handling code, a class
TWiki/Store/RcsWrap.pm
Wrappers around RCS executables, a class that inherits from RcsFile
TWiki/Store/RcsLite.pm
A Perl RCS implemention, a class that inherits from RcsFile
TWiki/Plugins/DefaultPlugin.pm
Handles some legacy rules
TWiki/Plugins/EmptyPlugin.pm
Empty plugin, use to create your own
TWiki/Plugins/InterwikiPlugin.pm
Use aliases as links for predefined URLs
Files under twiki/pub
The pub directory stores topic-related files, including images used by TWiki and FileAttachments. Attachments are stored in subdirectories created with the related topic name. You can also upload files directly for and link manually (but not through Attach) Partial file list:
Lookup table to translate file extension to file type
icn/bat.gif
GIF file for file type
icn/bmp.gif
GIF file for file type
...
...
TWiki/FileAttachment/Sample.txt
TEXT file: sample
TWiki/FileAttachment/Smile.gif
GIF image: sample
TWiki/FileAttachment/Smile.gif,v
RCS repository for GIF file
TWiki/PreviewBackground/blankltgraybg.gif
GIF image
TWiki/PreviewBackground/blankwhitebg.gif
GIF image
TWiki/PreviewBackground/previewbg.gif
GIF image: Preview view background
TWiki/PreviewBackground/preview2bg.gif
GIF image: Alternate preview view background
TWiki/TWikiLogos/twikiRobot121x54.gif
GIF image: TWiki logo
...
...
TWiki/TWikiTemplates/testscreen.gif
GIF image: Screen shot
TWiki/WabiSabi/wabisabi.gif
GIF image: illustration
Know/IncorrectDllVersionW32PTH10DLL/W32PTH10.DLL
DLL file: sample
Files under twiki/data
TWiki topics: data stored as individual text files and rendered by TWiki for display as regular Web pages. Each active web has its own subdirectory. The TWiki distribution includes four start-up webs - Main, TWiki, Know, Sandbox - with documentation and demo content, a Trash web for browser-based, recoverable topic deletion, and a _default directory containing a core topic set required to start a new web. Partial file list:
Rename/move control screen (choose web & new topic tile
renamebase.tmpl
Used by other rename templates
renameconfirm.tmpl
Confirms a pre-specified rename, ex: undoing a rename
renamerefs.tmpl
Display if rename done, but some references not changed (topics were locked)
search.tmpl
Search screen
searchbookview.tmpl
Search results with full topic content
searchformat.tmpl
Search screen for formatted search
searchmeta.tmpl
Search screen
searchrenameview.tmpl
Used by rename to list references to topic being renamed
twiki.tmpl
Master template: definitions are used by other templates
view.plain.tmpl
Skin for bare bone topic view without header/footer
view.print.tmpl
Skin for printable topic view with a simple header/footer
view.rss.tmpl
Skin for topic view in RDF XML format
view.tmpl
Main topic view - the standard regular Web page
TWiki File System Snapshot
The following partial directory listings from a Linux installation show typical file permissions and ownership. This is provided for general debugging use only and isn't an exact representation of the current distribution.
On an ISP installation... The user and group - twiki twiki - will probably be your domain or login name, eg: yourdomain yourdomain and can't be changed; same for nobody nobody files further down. Also, in the bin directory, scripts might need a .cgi (sometimes .pl) extension._
Directory twiki/bin:
drwxrwxr-x 2 twiki twiki 4096 Jan 7 23:56 .
drwxrwxr-x 5 twiki twiki 4096 Nov 18 12:21 ..
-rw-rw-r-- 1 twiki twiki 979 Aug 3 19:36 .htaccess
-rw-rw-r-- 1 twiki twiki 1598 Jun 1 2002 .htaccess.txt
-rwxrwxr-x 1 twiki twiki 4986 Jan 4 17:27 attach
-rwxrwxr-x 1 twiki twiki 3734 Jan 4 17:27 changes
-rwxrwxr-x 1 twiki twiki 9362 Jan 4 18:04 edit
-rwxrwxr-x 1 twiki twiki 1878 Jan 4 17:28 geturl
-rwxrwxr-x 1 twiki twiki 4587 Jan 4 17:28 installpasswd
-rwxrwxr-x 1 twiki twiki 7231 Jan 6 09:04 mailnotify
-rwxrwxr-x 1 twiki twiki 6000 Dec 11 01:26 makedistrib
-rwxrwxr-x 1 twiki twiki 8228 Jan 4 18:25 manage
-rwxrwxr-x 1 twiki twiki 2445 Jan 4 18:08 oops
-rwxrwxr-x 1 twiki twiki 6936 Jan 4 18:08 passwd
-rwxrwxr-x 1 twiki twiki 5820 Jan 4 17:30 preview
-rwxrwxr-x 1 twiki twiki 9235 Jan 4 17:31 rdiff
-rwxrwxr-x 1 twiki twiki 10584 Jan 4 18:09 register
-rwxrwxr-x 1 twiki twiki 14746 Jan 5 00:14 rename
-rwxrwxr-x 1 twiki twiki 4800 Jan 4 18:09 save
-rwxrwxr-x 1 twiki twiki 4729 Jan 4 17:32 search
-rw-rw-r-- 1 twiki twiki 1446 Jan 8 01:03 setlib.cfg
-rwxrwxr-x 1 twiki twiki 19261 Jan 4 17:33 statistics
-rwxrwxr-x 1 twiki twiki 30626 Jan 4 17:33 testenv
-rwxrwxr-x 1 twiki twiki 14306 Jan 4 18:11 upload
-rwxrwxr-x 1 twiki twiki 11414 Jan 5 01:12 view
-rwxrwxr-x 1 twiki twiki 2944 Jan 5 00:36 viewfile
Support for /bin/view/Web.TopicName topic view URL (besides the default /bin/view/Web/TopicName URL); useful for InterwikiPlugin links like TWiki:Codev.ReadmeFirst
In WebNotify, if only the WikiName is specified, the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
The page logo is configurable with new %WIKILOGOIMG%, %TWIKILOGOURL% and %WIKILOGOALT% variables in TWikiPreferences; replacing $wikiHomeUrl in TWiki.cfg
New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands
New topic templates as topics instead of templates. Customize by editing the topic. Retired notedited.tmpl, notext.tmpl and notwiki.tmpl templates. More in TWikiTemplates.
The table syntax has been enhanced to (i) render | *bold* | cells as table headers, (ii) render space padded cells | center aligned | and | right aligned |, (iii) span multiple columns using | empty cells |||. More in TextFormattingRules.
Security fix Questionable files like PHP scripts (executables) and .htaccess files that are attached to a topic get a .txt suffix appended to the file name. See also TWiki:Codev/FileAttachmentFilterSecurityAlert
New Wiki rule to specify arbitrary text for external links (i.e. [[http://TWki.org][TWiki]]) and internal links (i.e [[WikiSyntax][syntax]]). More in TWikiVariables.
New Wiki rule for named anchors, e.g. links within a topic. Define a named anchor with #MyAnchor at the beginning of a line, and link to it with [[#MyAnchor]]. More in TWikiVariables.
Format changed of %GMTIME{"..."}% and %SERVERTIME{"..."}% variables. Format is now "$hour:$min" instead of "hour:min". More in TWikiVariables. Attention: Check your existing topics when you upgrade TWiki!
WebChanges, WebSearch and e-mail notification indicate also the revision number of a topic (i.e. 18 Jan 2001 16:43 r1.5), or NEW for a new topic (i.e. i.e. 18 Jan 2001 16:43 NEW).
TWiki skins Define a different page layout with a customized header and footer layout, i.e. a print skin for a printable view of a topic. More in TWikiSkins and TWiki:Codev/TWikiSkins.
Improved include handling. Infinite recursion of includes are prevented; new variables %BASEWEB%, %INCLUDINGWEB%, %BASETOPIC% and %INCLUDINGTOPIC% to have more control over include handling. More in TWikiVariables and TWiki:Codev/IncludeHandlingImprovements.
New TWikiPreferences variables %HTTP_EQUIV_ON_VIEW% , %HTTP_EQUIV_ON_EDIT% and %HTTP_EQUIV_ON_PREVIEW% that define the <meta http-equiv="..."> meta tags for the TWiki templates. This can be used for example to set a document expiration time.
More forgiving syntax for *bold*, italic, __bold italic__ and fixed , where it is not necessary anymore to have a trailing space before .,;:?! characters.
Advanced search features like search multiple webs; sort by topic name / modified time / author; limit the number of results returned. More in TWikiVariables.
Uploading a file (topic file attachment) will optionally create a link to the uploaded file at the end of the topic. The preference variable %ATTACHLINKBOX% controls the default state of the link check box in the attach file page.
Edit preferences topics to set TWiki variables. There are three level of preferences Site-level (TWikiPreferences), web-level (WebPreferences in each web) and user-level preferences (for each of the TWikiUsers). With this, discontinue use of server side include of wikiwebs.inc , wikiwebtable.inc , weblist.inc , webcopyright.inc and webcolors.inc files.
New variable %SCRIPTSUFFIX% / $scriptSuffix containing an optional file extension of the TWiki Perl script. Templates have been changed to use this variable. This allows you to rename the Perl script files to have a file extension like for example ".cgi".
New variable %SCRIPTURLPATH% / $scriptUrlPath containing the script URL without the domain name. Templates have been changed to use this variable instead of %SCRIPTURL% . This is for performance reasons.
Changed the syntax for server side include variable from %INCLUDE:"filename.ext"% to %INCLUDE{"filename.ext"}% . (Previous syntax still supported. Change was done because of inline search syntax)
Inline search. New variable %SEARCH{"str" ...}% to show a search result embedded in a topic text. TWikiVariables has more on the syntax. Inline search combined with the category table feature can be used for example to create a simple bug tracking system.
Access statistics. Each web has a WebStatistics topic that shows monthy statistics with number of topic views and changes, most popular topics, and top contributors. (It needs to be enabled, TWikiDocumentation has more.)
Fixed bug where TWiki would not initialize correctly under certain circumstances, i.e. when running it under mod_perl. Sub initialize in wiki.pm did not handle $thePathInfo correctly.
Fixed bug where an email address starting with a WikiName was rendered as an internal Wiki link instead of an email address, i.e. SomeWikiName@somewhere.test .
Limit the number of revisions shown at the bottom of the topic. Example Topic TWikiHistory . { ..... Diffs r1.10 >r1.9>r1.8>r1.7>... } Additional revisions can be selected by pressing the >... link.
New text formatting rule for creating tables. Text gets rendered as a table if enclosed in " " vertical bars. Example line as it is written and how it shows up
Flag $doRemovePortNumber in wikicfg.pm to optionally remove the port number from the TWiki URL. Example www.some.domain:1234/twiki gets www.some.domain/twiki .
Search path for include files in %INCLUDE:"file.inc"% variable. Search first in the current web, then in parent data directory. Useful to overload default include text in the data directory by web-specific text, like for example webcopyright.inc text.
Link a plural topic to a singular topic in case the plural topic does not exist. Example TestVersion / TestVersions , TestPolicy / TestPolicies , TestAddress / TestAddresses , TestBox / TestBoxes .
Separate wiki.pm into configuration (wikicfg.pm) and TWiki core (wiki.pm) . This is to ease the upgrade of TWiki installations, it also allows customized extensions to TWiki without affecting the TWiki core.
New text formatting rule for creating fixed font text . Words get showns in fixed font by enclosing them in "=" equal signs. Example Writing =fixed font= will show up as fixed font .
Possible to view complete revision history of a topic on one page. Access at the linked date in the Changes page, or the Diffs link at the bottom of each topic, e.g. Topic TWikiHistory . { Edit Ref-By Diffs r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Possible to add a category table to a TWiki topic. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. TWikiDocumentation has more on setup. The TWiki.Know web uses this category table to set classification, platform and OS version.
Internal log of topic save actions to the file data/logYYYYMM.txt, where YYYYMM the year and month in numeric format is. Intended for auditing only, not accessible from the web.
The email notification and the Changes topic have now a topic date that is linked. Clicking on the link will show the difference between the two most recent topic revisions.
View differences between topic revisions. Each topic has a list of revisions (e.g. r1.3) and differences thereof (e.g. >) at the bottom Topic TWikiHistory . { Edit Ref-By r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Added revision control using RCS. Each topic has now a list of revisions at the bottom and a revision info, e.g. Topic TWikiHistory . { Edit Ref-By r1.3 r1.2 r1.1 } Revision r1.3 1998/10/26 01:34:00 by PeterThoeny
Refered-By Find out which topics have a link to the current topic. Each topic has a Ref-By link for that. Note Only references from the current web are shown, not references from other webs.
Topic WebChanges shows Wiki username instead of Intranet username, e.g. PeterThoeny instead of thoeny in case the Wiki username exists. Implementation Automatic lookup of Wiki username in topic TWikiUsers.
FAQ: How do I delete or rename a topic? Answer: New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously ...
FAQ: Why does the topic revision not increase when I edit a topic? Answer: The same topic revision will be used when you save a topic again within a certain time ...
FAQ: TWiki has a GPL (GNU General Public License). What is GPL? Answer: TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of ...
FAQ: I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer: That is an indication ...
FAQ: What happens if two of us try to edit the same topic simultaneously? Answer: The second person gets a warning that the topic is currently being edited by another ...
FAQ: I would like to install TWiki on my server. Can I get the source? Answer: TWiki is distributed under the GnuGeneralPublicLicense. You can request the source ...
FAQ: So what is this WikiWiki thing exactly? Answer: A set of pages of information that are open and free for anyone to edit as they wish. They are stored in a server ...
FAQ: Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer: TWiki is one of many WikiWikiClones, the first one was built by Ward Cunningham ...
NOTE: The FAQs here are for frequently asked questions including answers; please ask support questions in the TWiki:Support web. New FAQ topics are based on the TWikiFaqTemplate.
More sources...
Other places where you can find answers to your questions:
Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web & topic
Overview
By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. When forms are enabled for a web and selected in a topic, a single form appears in edit mode, and the contents are rendered as a table when viewed on the display page. You can define unlimited forms per web. For each topic, you can select a template if more than one is defined, or remove forms entirely. Form input values are stored as TWikiMetaData; all data is saved.
Form Templates replace TWikiCategoryTables from the 01-Dec-2000 version of TWiki.
Main Changes from Category Tables
The Form Template system is a more powerful, flexible replacement for the original TWikiCategoryTable. Data from existing category tables can be imported directly.
On upgrading from the previous TWiki, a Form Template topic has to be built for each web that used a Category Table, recreating the fields and values from the old twikicatitems.tmpl. The replacement Form Template must be set as the first item in the WebPreferences variable WEBFORMS. If missing, pages will display, but attempting to edit results in an error message.
The new Form Template system should work with old Category Table data with no special conversion. Data is assigned to Meta variables the first time an imported topic is edited and saved in the new system.
NOTE: If things aren't working correctly, there may be useful entries in data/warning.txt.
Defining a Form Template
A Form Template is simply a page containing your form, defined as a table where each row is one form field.
Form Template Elements
form template - a set of fields defining a form (replaces category table definition)
A web can use one or more form templates
form - a topic containing additional meta data (besides the freeform TEXTAREA) that categorizes the content (replaces category table)
Within a form-enabled web, individual topics can have a form or no form
form field - a named item in a form (replaces category item name)
field type - selects the INPUT type:
select - drop-down menu or scrollable box
checkbox - one or more checkboxes
checkbox+buttons - one or more checkboxes, plus Set and Clear buttons
radio - one or more radio buttons
text - a one-line text field
textarea - a text box; size is 40x10 (columns x rows)
field value - one or more values from a fixed set (select, checkbox, radio type) or free-form (text). (replaces category item value)
Defining a Form in One Topic
Create a new topic with your form name: YourForm, ExpenseReport, InfoCategory, RecordReview, whatever you need.
Create a TWiki table, with each column head representing one element of an entry field: Name, Type, Size, Values, and Tooltip message(see sample below).
For each field, fill in a new line; for the type of field, select from the list.
Save the topic (you can later choose to enable/disable individual forms).
Implementation Notes: This format allows you to define field items with or without WikiNames, depending on your needs.
Topics can be protected in the usual manner, using TWikiAccessControl, to limit who can change the form template and/or individual value lists.
[[...]] links can be used to force a link (at present, the [[...][...]] format is not supported).
The Tooltip message column is used as a tooltip for the field name (only if field name is a WikiName) - you only see the tooltip In edit.
The first item in the list is the default item. Alternative initial values can be set in a topic template, like WebTopicEditTemplate, with field=value, or, for checkboxes, field=1.
The topic definition is not read when a topic is viewed.
Enabling Forms by Web
Forms are enabled on a per web basis. The WEBFORMS variable in WebPreferences is optional and defines a list of possible form templates. Example:
Set WEBFORMS = BugForm, FeatureForm, BookLoanForm
With WEBFORMS enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS, or the No form option.
Including Forms in New Topics
A default Form Template (new topics get this default form) can be provided by creating the WebTopicEditTemplate topic in a web and adding a form to it. Initial Form values can be set there.
Additionally a new topic can be given a Form using the formtemplate parameter in the URL. Initial values can then be provided in the URLs or as form values:
other than checkboxes: name, ex: ?BugPriority=1
checkbox: namevalue=1, ex: ?ColourRed=1.
Boxes with a tick must be specified.
Setting Up Multiple Form Options
The optional WEBFORMS variable defines alternative forms that can be selected by pressing Change in edit mode.
A topic template can use any form.
New topics with a form are created by simple HTML forms asking for a topic name. For example, you can have a SubmitExpenseReport topic where you can create new expense reports, a SubmitVacationRequest topic, and so on. These can specify the required template topic with its associated form.
Form Data Storage
The form topic name, fields and values are stored as TWikiMetaData - the order of the field/value pairs is the same as in the template.
Using Form Data
TWikiForms accept user-input data, stored as TWikiMetaData. Meta data also contains program-generated info about changes, attachments, etc. To find, format and display form and other meta data, see TWikiMetaData, SEARCH and METASEARCH variables in TWikiVariables, and TWiki Formatted Search for various options.
-- JohnTalintyre - 16 Aug 2001
-- MikeMannix? - 05 Jan 2002
Official list of stable TWiki functions for Plugin developers
Description
This module defines official funtions that Plugins and add-on
scripts can use to interact with the TWiki engine and content.
Plugins should only use functions published in this module. If you use
functions in other TWiki libraries you might impose a security hole and
you will likely need to change your Plugin when you upgrade TWiki.
Functions: CGI Environment
getSessionValue( $key ) ==> $value
Description:
Get a session value from the Session Plugin (if installed)
Parameter: $key
Session key
Return: $value
Value associated with key; empty string if not set; undef if session plugin is not installed
setSessionValue( $key, $value ) ==> $result
Description:
Set a session value via the Session Plugin (if installed)
Parameter: $key
Session key
Parameter: $value
Value associated with key
Return: $result
"1" if success; undef if session plugin is not installed
getSkin( ) ==> $skin
Description:
Get the name of the skin, set by the SKIN preferences variable or the skin CGI parameter
Return: $skin
Name of skin, e.g. "gnu". Empty string if none
getUrlHost( ) ==> $host
Description:
Get protocol, domain and optional port of script URL
Return: $host
URL host, e.g. "http://example.com:80"
getScriptUrl( $web, $topic, $script ) ==> $url
Description:
Compose fully qualified URL
Parameter: $web
Web name, e.g. "Main"
Parameter: $topic
Topic name, e.g. "WebNotify"
Parameter: $script
Script name, e.g. "view"
Return: $url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
getScriptUrlPath( ) ==> $path
Description:
Get script URL path
Return: $path
URL path of TWiki scripts, e.g. "/cgi-bin"
getViewUrl( $web, $topic ) ==> $url
Description:
Compose fully qualified view URL
Parameter: $web
Web name, e.g. "Main". The current web is taken if empty
Parameter: $topic
Topic name, e.g. "WebNotify"
Return: $url
URL, e.g. "http://example.com:80/cgi-bin/view.pl/Main/WebNotify"
First extract text between {...} to get: "nameless" name1="val1" name2="val2"
Then call this on the text: my $noname = TWiki::Func::extractNameValuePair( $text ); my $name1 = TWiki::Func::extractNameValuePair( $text, "name1" ); my $name2 = TWiki::Func::extractNameValuePair( $text, "name2" );
getPreferencesValue( $key, $web ) ==> $value
Description:
Get a preferences value from TWiki or from a Plugin
Parameter: $key
Preferences key
Parameter: $web
Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value
Preferences value; empty string if not set
Example for Plugin setting:
MyPlugin topic has: * Set COLOR = red
Use "MYPLUGIN_COLOR" for $key
my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );
Example for preferences setting:
WebPreferences topic has: * Set WEBBGCOLOR = #FFFFC0
my $webColor = TWiki::Func::getPreferencesValue( "WEBBGCOLOR", "Sandbox" );
getPreferencesFlag( $key, $web ) ==> $value
Description:
Get a preferences flag from TWiki or from a Plugin
Parameter: $key
Preferences key
Parameter: $web
Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
Return: $value
Preferences flag "1" (if set), or "0" (for preferences values "off", "no" and "0")
Example for Plugin setting:
MyPlugin topic has: * Set SHOWHELP = off
Use "MYPLUGIN_SHOWHELP" for $key
my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );
getWikiToolName( ) ==> $name
Description:
Get toolname as defined in TWiki.cfg
Return: $name
Name of tool, e.g. "TWiki"
getMainWebname( ) ==> $name
Description:
Get name of Main web as defined in TWiki.cfg
Return: $name
Name, e.g. "Main"
getTwikiWebname( ) ==> $name
Description:
Get name of TWiki documentation web as defined in TWiki.cfg
Return: $name
Name, e.g. "TWiki"
Functions: User Handling and Access Control
getDefaultUserName( ) ==> $loginName
Description:
Get default user name as defined in TWiki.cfg's $defaultUserName
Return: $loginName
Default user name, e.g. "guest"
getWikiName( ) ==> $wikiName
Description:
Get Wiki name of logged in user
Return: $wikiName
Wiki Name, e.g. "JohnDoe"
getWikiUserName( $text ) ==> $wikiName
Description:
Get Wiki name of logged in user with web prefix
Return: $wikiName
Wiki Name, e.g. "Main.JohnDoe"
wikiToUserName( $wikiName ) ==> $loginName
Description:
Translate a Wiki name to a login name based on Main.TWikiUsers topic
The $oopsUrl for calling redirectCgiQuery(), user's $loginName, and estimated $unlockTime in minutes. The $oopsUrl and $loginName is empty if topic has no edit lock.
Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.
Parameter: $web
Web name, e.g. "Main", or empty
Parameter: $topic
Topic name, e.g. "MyTopic", or "Main.MyTopic"
Parameter: $text
Topic text to save, assumed to include meta data
Parameter: $ignorePermissions
Set to "1" if checkAccessPermission() is already performed and OK
Parameter: $dontNotify
Set to "1" if not to notify users of the change
Return: $oopsUrl
Empty string if OK; the $oopsUrl for calling redirectCgiQuery() in case of error
Example: my $oopsUrl = TWiki::Func::setTopicEditLock( $web, $topic, 1 ); if( $oopsUrl ) { TWiki::Func::redirectCgiQuery( $query, $oopsUrl ); # assuming valid query return; } my $text = TWiki::Func::readTopicText( $web, $topic ); # read topic text # check for oops URL in case of error: if( $text =~ /^http.*?\/oops/ ) { TWiki::Func::redirectCgiQuery( $query, $text ); return; } # do topic text manipulation like: $text =~ s/old/new/g; # do meta data manipulation like: $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/; $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text TWiki::Func::setTopicEditLock( $web, $topic, 0 ); # unlock topic if( $oopsUrl ) { TWiki::Func::redirectCgiQuery( $query, $oopsUrl ); return; }
getPublicWebList( ) ==> @webs
Description:
Get list of all public webs, e.g. all webs that do not have the NOSEARCHALL flag set in the WebPreferences
Return: @webs
List of all public webs, e.g. ( "Main", "Know", "TWiki" )
getTopicList( $web ) ==> @topics
Description:
Get list of all topics in a web
Parameter: $web
Web name, required, e.g. "Sandbox"
Return: @topics
Topic list, e.g. ( "WebChanges", "WebHome", "WebIndex", "WebNotify" )
Format type, optional. Default e.g. "31 Dec 2002 - 19:30", can be "iso" (e.g. "2002-12-31T19:30Z"), "rcs" (e.g. "2001/12/31 23:59:59", "http" for HTTP header format (e.g. "Thu, 23 Jul 1998 07:21:56 GMT")
Return: $text
Formatted time string
Functions: File I/O
getDataDir( ) ==> $dir
Description:
Get data directory (topic file root)
Return: $dir
Data directory, e.g. "/twiki/data"
getPubDir( ) ==> $dir
Description:
Get pub directory (file attachment root). Attachments are in $dir/Web/TopicName
Read text file, low level. NOTE: For topics use readTopicText()
Parameter: $filename
Full path name of file
Return: $text
Content of file
saveFile( $filename, $text )
Description:
Save text file, low level. NOTE: For topics use saveTopicText()
Parameter: $filename
Full path name of file
Parameter: $text
Text to save
Return:
none
writeWarning( $text )
Description:
Log Warning that may require admin intervention to data/warning.txt
Parameter: $text
Text to write; timestamp gets added
Return:
none
writeDebug( $text )
Description:
Log debug message to data/debug.txt
Parameter: $text
Text to write; timestamp gets added
Return:
none
Copyright and License
Copyright (C) 2000-2003 Peter Thoeny, Peter@Thoeny.com
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details, published at
http://www.gnu.org/copyleft/gpl.htmlNOTE: Above text is copied from the TWiki::Plugins/PerlDocPlugin output of TWiki::Func in twiki format. In case you want to get dynamically updated documentation based on the actual Perl module, install the PerlDocPlugin and replace above text with %PERLDOC{"TWiki::Func"}%.
-- PeterThoeny - 31 Dec 2002
A TWiki installation consisting of one or more webs. Details...
Skin:
Skins overlay regular templates with alternate header/footer layout of pages; topic text is not affected. Skins are typically enabled site-wide or per web. Details...
Templates:
(1) Regular templates define header/footer layout of pages; topic text is not affected. (2) Template topics set the default content for new topics. Details...
Topic:
The content of a TWiki page, consisting of text, an optional form and optional attachments. It has a WikiName that's unique within its web. Details...
TWiki:
A web-based collaboration platform targeting the corporate world. Contraction of "TakeFive Wiki". By chance, also happens to be the name of the AI robot star of the Buck Rogers 1979 movie and TV series. Features include browser based editing, automatic linking of text (based on ideas of the original WikiWikiWeb), revision control, file attachments, form handling, preferences settings, access control and more. Details...
TWiki.org:
Official home site, center of all development. Details...
Variables:
Text-strings of the form %VARIABLE% that are expanded on the fly into text, image, or any other type of embedded content; there are system variables coded into the main TWiki package, preferences settings, and Plugins variables. Details...
Web:
A collection of topics under a common name. Various features, like search, access privileges, Plugin availability, template design, can be controlled on a web-wide basis. Details...
-- MikeMannix? - 27 Aug 2001
-- PeterThoeny - 27 Jan 2003
Support for /bin/view/Web.TopicName topic view URL (besides the default /bin/view/Web/TopicName URL); useful for InterwikiPlugin links like TWiki:Codev.ReadmeFirst
In WebNotify, if only the WikiName is specified, the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
The page logo is configurable with new %WIKILOGOIMG%, %TWIKILOGOURL% and %WIKILOGOALT% variables in TWikiPreferences; replacing $wikiHomeUrl in TWiki.cfg
New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands
New topic templates as topics instead of templates. Customize by editing the topic. Retired notedited.tmpl, notext.tmpl and notwiki.tmpl templates. More in TWikiTemplates.
The table syntax has been enhanced to (i) render | *bold* | cells as table headers, (ii) render space padded cells | center aligned | and | right aligned |, (iii) span multiple columns using | empty cells |||. More in TextFormattingRules.
Security fix Questionable files like PHP scripts (executables) and .htaccess files that are attached to a topic get a .txt suffix appended to the file name. See also TWiki:Codev/FileAttachmentFilterSecurityAlert
New Wiki rule to specify arbitrary text for external links (i.e. [[http://TWki.org][TWiki]]) and internal links (i.e [[WikiSyntax][syntax]]). More in TWikiVariables.
New Wiki rule for named anchors, e.g. links within a topic. Define a named anchor with #MyAnchor at the beginning of a line, and link to it with [[#MyAnchor]]. More in TWikiVariables.
Format changed of %GMTIME{"..."}% and %SERVERTIME{"..."}% variables. Format is now "$hour:$min" instead of "hour:min". More in TWikiVariables. Attention: Check your existing topics when you upgrade TWiki!
WebChanges, WebSearch and e-mail notification indicate also the revision number of a topic (i.e. 18 Jan 2001 16:43 r1.5), or NEW for a new topic (i.e. i.e. 18 Jan 2001 16:43 NEW).
TWiki skins Define a different page layout with a customized header and footer layout, i.e. a print skin for a printable view of a topic. More in TWikiSkins and TWiki:Codev/TWikiSkins.
Improved include handling. Infinite recursion of includes are prevented; new variables %BASEWEB%, %INCLUDINGWEB%, %BASETOPIC% and %INCLUDINGTOPIC% to have more control over include handling. More in TWikiVariables and TWiki:Codev/IncludeHandlingImprovements.
New TWikiPreferences variables %HTTP_EQUIV_ON_VIEW% , %HTTP_EQUIV_ON_EDIT% and %HTTP_EQUIV_ON_PREVIEW% that define the <meta http-equiv="..."> meta tags for the TWiki templates. This can be used for example to set a document expiration time.
More forgiving syntax for *bold*, italic, __bold italic__ and fixed , where it is not necessary anymore to have a trailing space before .,;:?! characters.
Advanced search features like search multiple webs; sort by topic name / modified time / author; limit the number of results returned. More in TWikiVariables.
Uploading a file (topic file attachment) will optionally create a link to the uploaded file at the end of the topic. The preference variable %ATTACHLINKBOX% controls the default state of the link check box in the attach file page.
Edit preferences topics to set TWiki variables. There are three level of preferences Site-level (TWikiPreferences), web-level (WebPreferences in each web) and user-level preferences (for each of the TWikiUsers). With this, discontinue use of server side include of wikiwebs.inc , wikiwebtable.inc , weblist.inc , webcopyright.inc and webcolors.inc files.
New variable %SCRIPTSUFFIX% / $scriptSuffix containing an optional file extension of the TWiki Perl script. Templates have been changed to use this variable. This allows you to rename the Perl script files to have a file extension like for example ".cgi".
New variable %SCRIPTURLPATH% / $scriptUrlPath containing the script URL without the domain name. Templates have been changed to use this variable instead of %SCRIPTURL% . This is for performance reasons.
Changed the syntax for server side include variable from %INCLUDE:"filename.ext"% to %INCLUDE{"filename.ext"}% . (Previous syntax still supported. Change was done because of inline search syntax)
Inline search. New variable %SEARCH{"str" ...}% to show a search result embedded in a topic text. TWikiVariables has more on the syntax. Inline search combined with the category table feature can be used for example to create a simple bug tracking system.
Access statistics. Each web has a WebStatistics topic that shows monthy statistics with number of topic views and changes, most popular topics, and top contributors. (It needs to be enabled, TWikiDocumentation has more.)
Fixed bug where TWiki would not initialize correctly under certain circumstances, i.e. when running it under mod_perl. Sub initialize in wiki.pm did not handle $thePathInfo correctly.
Fixed bug where an email address starting with a WikiName was rendered as an internal Wiki link instead of an email address, i.e. SomeWikiName@somewhere.test .
Limit the number of revisions shown at the bottom of the topic. Example Topic TWikiHistory . { ..... Diffs r1.10 >r1.9>r1.8>r1.7>... } Additional revisions can be selected by pressing the >... link.
New text formatting rule for creating tables. Text gets rendered as a table if enclosed in " " vertical bars. Example line as it is written and how it shows up
Flag $doRemovePortNumber in wikicfg.pm to optionally remove the port number from the TWiki URL. Example www.some.domain:1234/twiki gets www.some.domain/twiki .
Search path for include files in %INCLUDE:"file.inc"% variable. Search first in the current web, then in parent data directory. Useful to overload default include text in the data directory by web-specific text, like for example webcopyright.inc text.
Link a plural topic to a singular topic in case the plural topic does not exist. Example TestVersion / TestVersions , TestPolicy / TestPolicies , TestAddress / TestAddresses , TestBox / TestBoxes .
Separate wiki.pm into configuration (wikicfg.pm) and TWiki core (wiki.pm) . This is to ease the upgrade of TWiki installations, it also allows customized extensions to TWiki without affecting the TWiki core.
New text formatting rule for creating fixed font text . Words get showns in fixed font by enclosing them in "=" equal signs. Example Writing =fixed font= will show up as fixed font .
Possible to view complete revision history of a topic on one page. Access at the linked date in the Changes page, or the Diffs link at the bottom of each topic, e.g. Topic TWikiHistory . { Edit Ref-By Diffs r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Possible to add a category table to a TWiki topic. This permits storing and searching for more structured information. Editing a topic shows a HTML form with the usual text area and a table with selectors, checkboxes, radio buttons and text fields. TWikiDocumentation has more on setup. The TWiki.Know web uses this category table to set classification, platform and OS version.
Internal log of topic save actions to the file data/logYYYYMM.txt, where YYYYMM the year and month in numeric format is. Intended for auditing only, not accessible from the web.
The email notification and the Changes topic have now a topic date that is linked. Clicking on the link will show the difference between the two most recent topic revisions.
View differences between topic revisions. Each topic has a list of revisions (e.g. r1.3) and differences thereof (e.g. >) at the bottom Topic TWikiHistory . { Edit Ref-By r1.3 > r1.2 > r1.1 } Revision r1.3 1998/11/10 01:34 by PeterThoeny
Added revision control using RCS. Each topic has now a list of revisions at the bottom and a revision info, e.g. Topic TWikiHistory . { Edit Ref-By r1.3 r1.2 r1.1 } Revision r1.3 1998/10/26 01:34:00 by PeterThoeny
Refered-By Find out which topics have a link to the current topic. Each topic has a Ref-By link for that. Note Only references from the current web are shown, not references from other webs.
Topic WebChanges shows Wiki username instead of Intranet username, e.g. PeterThoeny instead of thoeny in case the Wiki username exists. Implementation Automatic lookup of Wiki username in topic TWikiUsers.
Installation instructions for the TWiki 01-Feb-2003 production release. Update notes for the new RCS configuration are markedDataframework.
These installation steps are based on the Apache web server on Linux. TWiki runs on other web servers and Unix systems, and should be fine with any web server and OS that meet the system requirements. Documentation for other platforms is somewhat limited:
NOTE:If you don't have access to your Web server configuration files - for example, if you're installing on an ISP-hosted account, or you don't have administrator privileges on your intranet server - use the alternative Step 1 instead.
Create directory /home/httpd/twiki and unzip the TWiki distribution into this directory.
The twiki/bin directory of TWiki must be set as a cgi-bin directory. Add /home/httpd/twiki/bin to file /etc/httpd/httpd.conf with only ExecCGI option.
The twiki/pub directory of TWiki must be set so that it is visible as a URL. Add /home/httpd/twiki to file httpd.conf with normal access options (copy from /home/httpd/html ).
Now add ScriptAlias for /twiki/bin and Alias for /twiki to file httpd.conf .
NOTE: The ScriptAliasmust come before the Alias, otherwise, Apache will fail to correctly set up /twiki/bin/, by treating it as just another subdirectory of the /twiki/ alias.
The twiki/data and twiki/templates directories should be set so that they are not visible as URLs. Add them to httpd.conf with deny from all.
Example httpd.conf entries:
ScriptAlias /twiki/bin/ "/home/httpd/twiki/bin/"
Alias /twiki/ "/home/httpd/twiki/"
<Directory "/home/httpd/twiki/bin">
Options +ExecCGI
SetHandler cgi-script
Allow from all
</Directory>
<Directory "/home/httpd/twiki/pub">
Options FollowSymLinks +Includes
AllowOverride None
Allow from all
</Directory>
<Directory "/home/httpd/twiki/data">
deny from all
</Directory>
<Directory "/home/httpd/twiki/templates">
deny from all
</Directory>
Restart Apache by /etc/rc.d/rc5.d/S85httpd restart .
Test that the twiki/bin directory is CGI-enabled by trying visiting it in your browser:
Enter the URL for the bin directory, http://yourdomain.com/twiki/bin/.
Your settings are OK if you get a message like "Forbidden. You don't have permission to access /twiki/bin/ on this server".
Settings are NOT correct if you get something like "Index of /twiki/bin" - recheck your httpd.conf file.
To install TWiki on a system where you don't have Unix/Linux root (administrator) privileges, for example, on a hosted Web account or an intranet server administered by someone else:
Download and unzip TWiki on your local PC
Using the table below, create a directory structure on your host server
Upload the TWiki files by FTP (transfer as text except for the image files in pub)
If you are not able to create the twiki/lib directory at the same level as the twiki/bin directory (e.g. because CGI bin directories can't be under your home directory and you don't have root access), you can create this directory elsewhere and edit the setlib.cfg file in the bin directory:
# -------------- Change these settings if required
$twikiLibPath = '/some/other/path/lib'; # Path to lib directory containing TWiki.pm
You can also edit $localPerlLibPath in the setlib.cfg file if you are not root and need to install additional CPAN modules, but can't update the main Perl installation files on the server. Just set this variable to the full pathname to your local lib directory, typically under your home directory.
Step 2: Set File Permissions
Make sure Perl 5 and the Perl CGI library are installed on your system. The default location of Perl is /usr/bin/perl. If it's elsewhere, change the path to Perl in the first line of each script in the twiki/bin directory, or create a symbolic link from /usr/bin/perl.
IMPORTANT: On ISP-hosted accounts, Perl CGI scripts usually require a .cgi extension to run. Some systems need .pl, the regular Perl extension. Modify all twiki/bin script filenames if necessary.
Set the file permission of all Perl scripts in the twiki/bin directory as executable to -rwxr-xr-x (755).
To be able to edit the Perl scripts and .tmpl files it is necessary to chown and chgrp -R twiki so all the files have the owner you want.
This Guide assumes user nobody ownership for all files manipulated by the CGI scripts (executed by the Web server), and user twiki for all other files. You can:
replace nobody with another user if your server executes scripts under a different name (ex: default for Debian is www-data).
HINT: Run the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. It will show you the user name of the CGI scripts, a table listing all CGI environment variables, and a test of your twiki/lib/TWiki.cfg configuration file (you'll configure that in a minute).
replace user twiki with your own username
Set the permission of all files below twiki/data so that they are writable by user nobody. A simple way is to chmod them to -rw-rw-r-- (664) and to chown them to nobody.
Set the permission of the twiki/data directory and its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
Set the permission of the twiki/pub directory and all its subdirectories so that files in there are writable by user nobody. A simple way is to chmod them to drwxrwxr-x (775) and to chown them to nobody.
The twiki/data/*/*.txt,v RCS repository files in the installation package are locked by user nobody. If your CGI scripts are not running as user nobody, it's not possible to check in files (you'll see that the revision number won't increase after saving a topic). In this case, you need to unlock all repository files (check the RCS man pages) and lock them with a different user, ex www-data, or delete them all - new files will be automatically created the first time each topic is edited. A simple way to change ownership is with a search-and-replace in all files; for example, using perl:
cd twiki/data
perl -pi~ -e 's/nobody:/www-data:/' */*,v
Step 3: Set the Main Configuration File
Edit the file twiki/lib/TWiki.cfg, setting the variables to your needs.
Set the file extension in the $scriptSuffix variable to cgi or pl if required.
RCS - revision control system to store revision of topics and attachments. You can use RCS executables or a version of RCS written in Perl, note that as the time of writing (Apr 2002) the Perl version has not been widely tested, so if you want to put up a live site the RCS executables are recommended.
Set $storeTopicImpl = "RcsWrap"; for the RCS executables and make sure RCS is installed. Set $rcsDir in twiki/lib/TWiki.cfg to match the location of your RCS binaries. You can check this by issuing the command rcs at the prompt, it should result in something like "rcs: no input file".
Check that you have GNU diff, by typing diff -v - an error indicates you have a non-GNU diff, so install the GNU diffutils package and make sure that diff is on the PATH used by TWiki (see $safeEnvPath in the TWiki.cfg file).
Set $storeTopicImpl = "RcsLite"; for the Perl based RCS
Security issue: Directories twiki/data , twiki/templates and all their subdirectories should be set so that they are not visible through URLs. (Alternatively, move the directories to a place where they are not visible, and change the variables in twiki/lib/TWiki.cfg accordingly)
Test your settings by running the testenv script from your browser: http://yourdomain.com/twiki/bin/testenv. Check if your twiki/lib/TWiki.cfg configuration file settings are correct.
Step 4: Configure Site-Wide Email Preferences
From your web browser, edit the TWikiPreferences topic in the TWiki:TWiki web to set the WIKIWEBMASTER email address, and other email settings required for registration and WebChangesAlert to work:
WIKIWEBMASTER should be set to the email address of the TWiki administrator
SMTPMAILHOST is typically set on Windows or other non-Unix/Linux systems, where sendmail or similar is not available. When this is set and the Perl module Net::SMTP is installed, TWiki will connect to this SMTP server (e.g. mail.yourdomain.com) to send email for user registration and WebChangesAlerts. If you do have a sendmail-type program, leave SMTPMAILHOST unset so that the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg).
SMTPSENDERHOST is optional, and set to the domain name sending the email (e.g. twiki.yourdomain.com). For use where the SMTP server requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you.
Point your Web browser at http://yourdomain.com/twiki/bin/view and start TWiki-ing away!
Or, point to http://yourdomain.com/twiki/ to get the pre-TWiki index.html page, with a link to the view script. Customize this page if you want a public intro screen with a login link, instead of immediately calling up the .htaccess login dialog by going directly to view.
Edit the WebPreferences topic in each web, if necessary: set individual WEBCOPYRIGHT messages, and other preferences.
Enable email notification of topic changes, TWikiSiteTools has more.
Edit the WebNotify topic in all webs and add the users you want to notify.
That's it for the standard virgin installation of TWiki. Read on for server-level customization options.
Additional Server-Level Options
With your new TWiki installation up and running, you can manage most aspects of your site from the browser interface. Only a few functions require access to the server file system, via Telnet or FTP. You can make these server-level changes during installation, and at any time afterwards.
Enabling Authentication of Users
If TWiki is installed on a non-authenticated server - not using SSL - and you'd like to authenticate users:
Rename file .htaccess.txt in the twiki/bin directory to .htaccess and change it to your needs. For details, consult the HTTP server documentation (for Apache server: [1], [2]). In particular, the following red part needs to be configured correctly: Redirect /urlpathto/twiki/index.html http://yourdomain.com/urlpathto/twiki/bin/view AuthUserFile /filepathto/twiki/data/.htpasswd ErrorDocument 401 /urlpathto/twiki/bin/oops/TWiki/TWikiRegistration?template=oopsauth
NOTE: If you had to add a .cgi or .pl file extension to the bin scripts, make sure to do the same for edit, view, preview, and all the other script names in .htaccess.
The browser should ask for login name and password when you click on the Edit link. In case .htaccess does not have the desired effect, you need to enable it: Add "AllowOverride All" to the Directory [3] section of access.conf for your twiki/bin directory.
This applies only if you have root access: on hosted accounts, you shouldn't have this problem - otherwise, email tech support.
NOTE: In the TWiki distribution package, the twiki/data/.htpasswd.txt file contains several TWiki core team user accounts and a guest user account. You probably want to remove those accounts by deleting the entries in .htpasswd. Do not remove the guest user if you want to allow guest logins.
Copy the TWikiRegistrationPub? topic to TWikiRegistration, overwriting old version of TWikiRegistration. Do that by either editing the topics in theTWiki web, or by renaming the .txt and .txt,v files in the twiki/data/TWiki directory.
Customization:
You can customize the registration form by deleting or adding input tags. The name="" parameter of the input tags must start with: "Twk0..." (if this is an optional entry), or "Twk1..." (if this is a required entry). This ensures that the fields are carried over into the user home page correctly.
You can customize the default user home page in NewUserTemplate.
NOTE: When a user registers, a new line with the username and encrypted password is added to the data/.htpasswd file. The .htpasswd file that comes with the TWiki installation includes user accounts for TWiki core team members that are used for testing on TWiki.org. You can edit the file and delete those lines.
Create a new topic to check if authentication works.
Edit the TWikiAdminGroup topic in the TWiki:Main web to include users with system administrator status.
Edit the WebPreferences topic in each web, if necessary: set access priviliges.
That's it for a basic new web set-up!
Optionally, you can also:
Create custom web-specific templates in a new twiki/templates/Someweb directory (otherwise, templates are inherited from twiki/templates).
Add TWikiForms for form-based page input that's stored separately from the main free-form topic text.
NOTE: User home topics are located in the TWiki.Main web - don't try to move them or create them in other webs. From any other web, user signatures have to point to TWiki.Main web, using a Main.UserName or %MAINWEB%.UserName format. (The %MAINWEB% variable is an advantage if you ever change the Main web name, but the standard Main.UserName is easier for users to enter, which is the bottom line!
TWiki File System Info
See Appendix A: TWiki File System for an installed system snapshot and descriptions of all files in the TWiki 01-Sep-2001 distribution.
-- PeterThoeny - 28 Dec 2002
-- MikeMannix? - 16 May 2002
Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs
Overview
TWikiMetaData uses META variables to store topic data that's separate from the main free-form content. This includes program-generated info like FileAttachment and topic movement data, and user-defined TWikiForms info. Use META variables to format and display Meta Data.
Meta Data Syntax
Format is the same as in TWikiVariables, except all fields have a key.
%META:<type>{key1="value1" key2="value2" ...}%
Order of fields within the meta variables is not defined, except that if there is a field with key name, this appears first for easier searching (note the order of the variables themselves is defined).
Each meta variable is on one line.
\n (new line) is represented in values by %_N_ and " (double-quotes) by %_Q_%.
Example of Format
%META:TOPICINFO{version="1.6" date="976762663" author="PeterThoeny" format="1.0"}%
text of the topic
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName"
by="JohnTalintyre" date="976762680"}%
%META:TOPICPARENT{name="NavigationByTopicContext"}%
%META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }%
%META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }%
%META:FORM{name="WebFormTemplate"}%
%META:FIELD{name="OperatingSystem" value="OsWin"}%
%META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Meta Data Specifications
The current version of Meta Data is 1.0, with support for the following variables.
Format of this topic, will be used for automatic format conversion
META:TOPICMOVED
This is optional, exists if topic has ever been moved. If a topic is moved more than once, only the most recent META:TOPICMOVED meta variable exists in the topic, older ones are to be found in the rcs history.
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
The topic from which this was created, WebHome if done from Go, othewise topic where ? or form used. Normally just topic, but is full web.topic format if parent is in a different Web. Renaming a Web will then only break a few of these references or they can be scanned and fixed.
There is no absolute need for Meta Data variables to be listed in a specific order within a topic, but it makes sense to do so a couple of good reasons:
form fields remain in the order they are defined
the diff function output appears in a logical order
The recommended sequence is:
META:TOPICINFO
text of topic
META:TOPICMOVED (optional)
META:TOPICPARENT (optional)
META:FILEATTACHMENT (0 or more entries)
META:FORM (optional)
META:FIELD (0 or more entries; FORM required)
Viewing Meta Data in Page Source
When viewing a topic the Raw Text link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on to URL. raw=debug shows the meta data as well as the topic data, ex: debug view for this topic
Rendering Meta Data
Meta Data is rendered with the %META% variable. This is mostly used in the view, preview and edit scripts.
Current support covers:
Show attachments, except for hidden ones. Options: all="on": Show all attachments, including hidden ones.
%META{"moved"}%
Details of any topic moves.
%META{"parent"}%
Show topic parent. Options: dontrecurse="on": By default recurses up tree, at some cost. nowebhome="on": Suppress WebHome. prefix="...": Prefix for parents, only if there are parents, default "". suffix="...": Suffix, only appears if there are parents, default "". separator="...": Separator between parents, default is " > ".
Known Issues
At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the Meta.pm code that supports the format needs only minor alteration.
-- JohnTalintyre - 29 Aug 2001
-- MikeMannix - 03 Dec 2001
-- PeterThoeny - 10 Jan 2002
Plug-in enhanced feature add-ons, with a Plugin API for developers
Overview
You can add Plugins to extend TWiki's functionality, without altering the core program code. A plug-in approach lets you:
add virtually unlimited features while keeping the main TWiki code compact and efficient;
heavily customize an installation and still do clean updates to new versions of TWiki;
rapidly develop new TWiki functions in Perl using the Plugin API.
Everything to do with TWiki Plugins - demos, new releases, downloads, development, general discussion - is available at TWiki.org, in the TWiki:Plugins web.
Preinstalled Plugins
TWiki comes with three Plugins as part of the standard installation.
DefaultPlugin optionally handles some legacy variables from older versions of TWiki. You can control this option from TWikiPreferences. (Perl programmers can also add rules for simple custom processing.)
EmptyPlugin is a fully functional module, minus active code; it does nothing and serves as a template for new Plugin development.
InterwikiPlugin is preinstalled but can be disabled or removed. Use it for shorthand linking to remote sites, ex: TWiki:Plugins expands to TWiki:Plugins on TWiki.org. You can edit the predefined set of of Wiki-related sites, and add your own.
Installing Plugins
Each TWikiPlugin comes with full documentation: step-by-step installation instructions, a detailed description of any special requirements, version details, and a working example for testing.
Most Plugins can be installed in three easy steps, with no programming skills required:
Download the zip file containing the Plugin, documentation, and any other required files, from TWiki:Plugins.
Distribute the files to their proper locations - unzip the zip archive in your TWiki installation directory - if have a standard TWiki installation, this will distribute automatically. Otherwise, place the files according to the directory paths listed on the Plugin top in TWiki:Plugins.
Check the demo example on the Plugin topic: if it's working, the installation was fine!
Special Requests: Some Plugins need certain Perl modules to be preinstalled on the host system. Plugins may also use other resources, like graphics, other modules, applications, templates. In these cases, detailed instructions are in the Plugin documentation.
Each Plugin has a standard release page, located in the TWiki:Plugins web at TWiki.org. In addition to the documentation topic (SomePlugin), there's a separate development page.
Doc page: Read all available info about the Plugin; download the attached distribution files.
Dev page: Post feature requests, bug reports and general dev comments; topic title ends in Dev (SomePluginDev).
User support: Post installation, how to use type questions (and answers, if you have them) in the TWiki:Support web.
On-Site Pretesting
To test new Plugins on your installation before making them public, you may want to use one of these two approaches:
Method 1: Safely test on-the-fly by creating separate Production and Test branches in your live TWiki installation.
Duplicate the twiki/bin and twiki/lib directories for the Test version, adjusting the paths in the new lib/TWiki.cfg, the twiki/data; the twiki/templates and twiki/pub directories are shared.
Test Plugins and other new features in the Test installation until you're satisfied.
If you modify topics using the new features, live users will likely see unfamiliar new META tags showing up on their pages - to avoid this, create and edit test-only topics to try out new features.
Copy the modified files to the Production installation. You can update a TWiki installation live and users won't even notice.
Method 2: List the Plugin being tested in the DISABLEDPLUGINS variable in TWikiPreferences. Redefine the DISABLEDPLUGINS variable in the Sandbox web and do the testing there.
Managing Plugins
When you finish installing a Plugin, you should be able to read the user instructions and go. In fact, some Plugins require additional settings or offer extra options that you have to select. Also, you may want to make a Plugin available only in certain webs, or temporarily disable it. And may want to list all available Plugins in certain topics. You can handle all of these management tasks with simple procedures.
Setting Preferences
Installed Plugins can be toggled on or off, site-wide or by web, through TWikiPreferences and individual WebPreferences:
All Plugin modules present in the lib/TWiki/Plugins directory are activated automatically unless disabled by the DISABLEDPLUGINS Preferences variable in TWikiPreferences. You can optionally list the installed Plugins in the INSTALLEDPLUGINS Preferences variable. This is useful to define the sequence of Plugin execution, or to specify other webs than the TWiki web for the Plugin topics. Settings in TWikiPreferences are:
Set INSTALLEDPLUGINS = DefaultPlugin, ...
Set DISABLEDPLUGINS = EmptyPlugin, ...
Plugin execution order in TWiki is determined by searching Plugin topics in a specific sequence: First, full web.topicname name, if specified in INSTALLEDPLUGINS; next, the TWiki web is searched; and finally, the current web.
Plugin-specific settings are done in individual Plugin topics. Two settings are standard for each Plugin:
One line description, used to form the bullets describing the Plugins in the TextFormattingRules topic:
Set SHORTDESCRIPTION = Blah blah woof woof.
Debug Plugin, output can be seen in data/debug.txt. Set to 0=off or 1=on:
Set DEBUG = 0
The settings can be retrieved as Preferences variables like %<pluginname>_<var>%, ex: %DEFAULTPLUGIN_SHORTDESCRIPTION% shows the description of the DefaultPlugin.
Listing Active Plugins
Plugin status variables let you list all active Plugins wherever needed. There are two list formats:
The %ACTIVATEDPLUGINS% variable lists activated Plugins by name. (This variable is displayed in TWikiPreferences for debugging use.)
The %PLUGINDESCRIPTIONS% variable displays a bullet list with a one-line description of each active Plugins. This variable is based on the %<plugin>_SHORTDESCRIPTION% Preferences variables of individual topics and is shown in TextFormattingRules.
DEMO: Automatically List Active Plugins Using Variables
Using %ACTIVATEDPLUGINS%:
On this TWiki site, the active Plugins are: DefaultPlugin, EditTablePlugin, InterwikiPlugin, TablePlugin.
Using %PLUGINDESCRIPTIONS%:
You can use any of these active TWiki Plugins:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
The TWiki Plugin API
The Application Programming Interface (API) for TWikiPlugins provides the specifications for hooking into the core TWiki code from your external Perl Plugin module. The Plugin API is new to the Production version of TWiki with the 01-Sep-2001 release.
Available Core Functions
The TWikiFuncModule (lib/TWiki/Func.pm) implements ALL official Plugin functions. Plugins should ONLY use functions published in this module.
If you use functions not in Func.pm, you run the risk of creating security holes. Also, your Plugin will likely break and require updating when you upgrade to a new version of TWiki.
Predefined Hooks
In addition to TWiki core functions, Plugins can use predefined hooks, or call backs, listed in the lib/TWiki/Plugins/EmptyPlugin.pm module.
All but the initPlugin are disabled. To enable a call back, remove DISABLE_ from the function name.
For best performance, enable only the functions you really need. NOTE: outsidePREHandler and insidePREHandler are particularly expensive.
Plugin Version Detection
To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system and an API GetVersion detection routine are provided for automatic compatibility checking.
All modules require a $VERSION='0.000' variable, beginning at 1.000.
The initPlugin handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
The Plugin initialization code does not register a Plugin that returns FALSE (or that has no initPlugin handler).
With a reasonable knowledge of the Perl scripting language, you can create new Plugins or modify and extend existing ones. Basic plug-in architecture uses an Application Programming Interface (API), a set of software instructions that allow external code to interact with the main program. The TWiki Plugin API Plugins by providing a programming interface for TWiki.
The DefaultPlugin Alternative
DefaultPlugin can handle some outdated TWiki variables, found, for example, in sites recently updated from an old version. Settings are in DefaultPlugin topic. You can also add your own simple custom processing rules here, though in all but very simple cases, writing a new Plugin is preferable.
Anatomy of a Plugin
A basic TWiki Plugin consists of two elements:
a Perl module, ex: MyFirstPlugin.pm
a documentation topic, ex: MyFirstPlugin.txt
The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call.
In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the MyFirstPlugin topic. Other needed Perl code is best placed in a lib/TWiki/Plugins/MyFirstPlugin/ directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the Plugin API, you're ready to develop Plugins.
Creating the Perl Module
Copy file lib/TWiki/Plugins/EmptyPlugin.pm to <name>Plugin.pm. The EmptyPlugin.pm module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the Plugin API specs for more information.
If your Plugin uses its own modules and objects, you must include the name of the Plugin in the package name. For example, write Package MyFirstPlugin::Attrs; instead of just Package Attrs;. Then call it using:
use TWiki::Plugins::MyFirstPlugin::Attrs;
$var = MyFirstPlugin::Attrs->new();
Writing the Documentation Topic
The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as FileAttachments for downloading. (The doc topic is also included in the distribution package.) To create a documentation topic:
OUTLINE: Doc Topic Contents
Check the Plugins web on TWiki.org for the latest Plugin doc topic template. Here's a quick overview of what's covered:
Syntax Rules: <Describe any special text formatting that will be rendered.>"
Example: <Include an example of the Plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>"
Plugin Global Settings: <Description and settings for custom Plugin %VARIABLES%, and those required by TWiki.>"
Plugins Preferences <If user settings are needed, explain... Entering values works exactly like TWikiPreferences and WebPreferences: six (6) spaces and then:>"
Set <EXAMPLE = value added>
Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>"
Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the TWiki:Plugins web.>"
Packaging for Distribution
A minimum Plugin release consists of a Perl module with a WikiName that ends in Plugin, ex: MyFirstPlugin.pm, and a documentation page with the same name(MyFirstPlugin.txt).
Distribute the Plugin files in a directory structure that mirrors TWiki. If your Plugin uses additional files, include them ALL:
Create a zip archive with the Plugin name (MyFirstPlugin.zip) and add the entire directory structure from Step 1. The archive should look like this:
lib/TWiki/Plugins/MyFirstPlugin.pm
data/TWiki/MyFirstPlugin.txt
pub/TWiki/MyFirstPlugin/uparrow.gif
Publishing for Public Use
You can release your tested, packaged Plugin to the TWiki community through the TWiki:Plugins web. All Plugins submitted to TWiki.org are available for download and further development in TWiki:Plugins. Publish your Plugin in three steps:
Post the Plugin documentation topic in the TWiki:Plugins web:
create a new topic using the Plugin name, ex: MyFirstPlugin.txt
Attach the distribution zip file to the topic, ex: MyFirstPlugin.zip
Link from the doc page to a new, blank page named after the Plugin, and ending in Dev, ex: MyFirstPluginDev. This is the discussion page for future development. (User support for Plugins is handled in TWiki:Support.)
The following are site-level settings that affect all users in all webs on this TWikiSite. They can be selectively overwritten on the individual web level (see WebPreferences in each web), and on the user level (create preferences in your user account topic in the Main web, ex: Main.guest).
NOTE: You can lock individual settings at the site or web levels using User & Group Access Control - see section below.
Exclude web from a web="all" search: (Set to on for hidden webs; is overwritten by web preferences)
Set NOSEARCHALL =
Prevent automatic linking of WikiWords and acronyms (if set to on); link WikiWords (if empty); can be overwritten by web preferences:
Set NOAUTOLINK =
Note: Use the [[...][...]] syntax to link topics in case you disabled WikiWord linking. The <noautolink> ... </noautolink> syntax can be used to prevents links within a block of text.
User Settings
NOTE: They are typically redefined in topics of individual TWikiUsers
Horizontal size of text edit box: (can be overwritten by user preferences)
Set EDITBOXWIDTH = 70
Vertical size of text edit box: (can be overwritten by user preferences)
Set EDITBOXHEIGHT = 15
Style of text edit box. Set to width: 99% for full window width (default; this will overwrite the EDITBOXWIDTH setting), or width: auto to disable. This setting works for IE and some other recent browsers. (can be overwritten by user preferences)
Set EDITBOXSTYLE = width: 99%
Default state of the Release edit lock (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time: (can be overwritten by user preferences)
Set RELEASEEDITLOCKCHECKBOX = checked
Default state of the Minor Changes, Don't Notify (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty: (can be overwritten by user preferences)
Set DONTNOTIFYCHECKBOX = checked
Default state of the link check box in the attach file page. Checkbox is initially checked if Set ATTACHLINKBOX = checked="checked", or unchecked if empty (Set ATTACHLINKBOX =). If checked, a link is created to the attached file at the end of the topic: (can be overwritten by user preferences)
Set ATTACHLINKBOX =
Format of file link when the link check box is checked: (can be overwritten by user preferences)
NOTE: Keyword $name gets expanded to filename; $comment to comment; \t to tab (3 spaces for bullets).
Format of images when the link check box is checked: (can be overwritten by user preferences)
NOTE: Keyword $name gets expanded to filename; $comment to comment; $size to width="..." height="..." attribute of img tag; \t to tab (3 spaces for bullets).
Mail host for outgoing mail. This is used for WebChangesAlert if Perl module Net::SMTP is installed. If not, or if SMTPMAILHOST is empty, the external sendmail program is used instead (defined by $mailProgram in TWiki.cfg). Examples: mail.your.company or localhost
Set SMTPMAILHOST = mail
Mail domain sending mail. SMTP requires that you identify the TWiki server sending mail. If not set, Net::SMTP will guess it for you. Ex: twiki.your.company
Set SMTPSENDERHOST =
Proxy Server. Some environments require outbound HTTP traffic to go through a proxy server. Set the host in PROXYHOST (example: proxy.your.company), and the port number in PROXYPORT (example: 8080). No proxy is used if PROXYHOST or PROXYPORT is empty.
Set PROXYHOST =
Set PROXYPORT =
Email Link Settings
'Mail this topic' mailto: link - can be included in topics, templates or skins
TWikiPlugins configuration: All plugin modules that exist in the lib/TWiki/Plugins directory are activated automatically unless disabled by DISABLEDPLUGINS. You can optionally list the installed plugins in INSTALLEDPLUGINS. This is useful to define the sequence of plugin execution, or to specify other webs then the TWiki web for the plugin topics. Specify plugins as a comma separated list of topics.
NOTE: You can enable/disable all plugins with the $disableAllPlugins flag in the lib/TWiki.cfg file.
HTTP-EQUIV Settings
http-equiv meta tags for view, rdiff, attach, search* scripts:
* Set HTTP_EQUIV_ON_VIEW =
http-equiv meta tags for edit script. Example, to expire immediately: Set HTTP_EQUIV_ON_EDIT = <meta http-equiv="Expires" content="%GMTIME{"$day $month $year $hour:$min:$sec"}% GMT">
%RED% red text %ENDCOLOR% and %GREEN% green text %ENDCOLOR%
You get:
red text and green text
Note:%<color>% text must end with %ENDCOLOR% . If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%.
Set YELLOW =
YELLOW looks like this
Set ORANGE =
ORANGE looks like this
Set RED =
RED looks like this
Set PINK =
PINK looks like this
Set PURPLE =
PURPLE looks like this
Set TEAL =
TEAL looks like this
Set NAVY =
NAVY looks like this
Set BLUE =
BLUE looks like this
Set AQUA =
AQUA looks like this
Set LIME =
LIME looks like this
Set GREEN =
GREEN looks like this
Set OLIVE =
OLIVE looks like this
Set MAROON =
MAROON looks like this
Set BLACK =
BLACK looks like this
Set GRAY =
GRAY looks like this
Set SILVER =
SILVER looks like this
Set WHITE =
WHITE looks like this
And finally:
Set ENDCOLOR =
To finish colored text
Graphics used in TWiki documentation - view all images in TWikiDocGraphics. (There are various ways to set up common icons as text variables. This is simply one quick approach.):
Set H =
Set I =
Set M =
Set N =
Set P =
Set Q =
Set S =
Set T =
Set U =
Set X =
Set Y =
Background color of non existing topic: ( default cornsilk or #FFFFCE )
Set NEWTOPICBGCOLOR = #FFFFCE
Font color of non existing topic: ( default #0000FF )
Site-level preferences that are not allowed to be overridden by WebPreferences and user preferences:
Set FINALPREFERENCES = PREVIEWBGIMAGE, WIKITOOLNAME, WIKIWEBMASTER, SMTPMAILHOST , SMTPSENDERHOST, ALLOWWEBMANAGE
Creating New Preference Variables
You can introduce new VARIABLES and use them in your topics and templates. There is no need to change the TWiki engine (Perl scripts).
A preference is defined in a TWikiShorthand bullet item: [3 spaces] * [space] Set NAME = value Example (as a nested bullet item, indented 6 spaces):
Set WEBBGCOLOR = #FFFFC0
Preferences are used as TWikiVariables by enclosing the name in percent signs: %. Example:
When you write variable %WEBBGCOLOR%, it gets expanded to #FFE0B0 .
The sequential order of the preference settings is significant. Define preferences that use other preferences FIRST. For example, set WEBCOPYRIGHT before WIKIWEBMASTER since the copyright notice uses the webmaster email address.
To edit pages on this TWiki Collaborative Web, you must have a registered user name in WikiNotation.
To register as a new user, simply fill out this form:
Submitting the form will automatically:
Create an account for you, so that you can start editing pages using your WikiName.
Create your personal TWiki topic using your WikiName as topic name, and add the data you submitted to the topic.
Add your name to the list of users in the TWikiUsers topic in the Main web.
Send you a confirmation of your registration by email.
Once registered you can login using your WikiName and password.
If you have any questions about registration, send an email to caad-yearly@hbt.arch.ethz.ch.
If you can enter text, you're ready for TWiki. With a few simple, intuitive TextFormattingRules, you'll be able to use plain text to create well-styled postings, instantly. Here's a fast-track guide to shorthand basics...
Separate each paragraph with a blank line.
To display a word or phrase in bold type, put it in asterisks: *bold type*.
To display a word or phrase in italic, put it in underscores: _italic_.
To display a word or phrase in bold italic, put it in double underscores: __bold italic__.
To link to another Wiki topic, type the WikiWord for that topic. To link to a Wiki topic in another web, type the name of the web, and a dot, first: Sandbox.WebHome.
If you enter a WikiWord for a topic that doesn't exist, it'll appear highlighted, with question mark at the end, prompting you (or someone else) to start off the new topic by clicking the ? - NewTopic? (click the ?, but don't save, to preserve the example!).
When entering WikiName signatures - like, guest - include "Main." as a prefix, since all TWiki member pages are in the Main web: Main.YourName.
For an external link, type the full URL: http://twiki.org/.
To prevent a WikiWord from becoming a link, type <nop> first, <nop>NoLinkPlease.
To indent with a bullet, enter [space][space][space][asterisk][space].
Use multiples of 3 spaces to start nested bullets.
That's 3-6-9-...
Start items in a numbered list with [space][space][space][1][space].
The "1" (or any number) will be replaced by the correct number, in order.
To add a new paragraph without restarting list numbering, use the %BR% variable, like below: Text added (in new paragraph)
and list numbering continues.
Always start counting spaces for bullets and such from the beginning of a new line.
To include an image, type its URL. You also can Attach an image to the page and display it with text %ATTACHURL%/yourimagefilename.jpg .
To display a word or phrase in MONOSPACED TYPE, put it in equal signs: =like this=. Use ==two== for bold: bold mono.
Use <verbatim> to enclose code excerpts, filenames, and other unformatted text, with the opening and closing tags on their own separate lines:
<verbatim>
unformatted text!
</verbatim>
Three (or more) consecutive hyphens expand into a horizontal rule: ---
TWiki provides an intuitive way for people to meet and collaborate, that aspires to the Zen ideals known as WabiSabi. It finds beauty in the imperfect and ephemeral and constantly evolving. (When it comes down to it, that's all you need.)
Wiki wiki means "quick" in Hawaiian. The shuttle at Honolulu Airport is called the wiki wiki bus, which is where the original Wiki web got its name.
TWiki is short for TakeFive Wiki, the name of the company where its founder worked. (It was later discovered that Twiki is also the name of an AI robot that co-starred in the Buck Rogers... movie and TV series from 1979 - see TWiki in the logo.)
Selected TWiki Topics...
TWikiSite provides a basic big picture overview of the TWiki platform
TWikiTopics is a quick and concentrated look at the TWiki core
WikiCulture looks at the unique type of collaboration Wiki systems offer.
WikiReferences links to articles and books about collaboration and Wiki technology.
If you have to log-in to use TWiki, for example, if Twiki is running on an intranet, it automatically signs pages you edit and create with your WikiName. If your TWiki installation doesn't require a log-in, TWiki gives everyone the same username: TWikiGuest.
TWikiTM is a trademark of PeterThoeny, originator and lead developer.
TWiki is developed as Free Software under the GNU/GPL
Utilities for searching, navigation, and monitoring site activityTWikiSiteTools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the TWiki web. In particular, TWiki provides two highly configurable, automated site monitoring tools, WebNotify, to email alerts when topics are edited, and WebStats, to generate detailed activity reports.
WebNotify Recent Changes Alert
Each TWiki web has an automatic email alert service that sends a list of recent changes on a preset schedule, like once a day. Users can subscribe and unsubscribe using WebNotify in each web. The Perl script mailnotify is called by a background process at regular intervals. The script sends an automated email to subscribed users if topics were changed in a web since the script was last run.
The first entry is the default form, the notification gets sent to the e-mail address specified in the user's home page. The second entry lists an alternative e-mail address. The third entry specifies a group, the notification gets sent to each member of the group.
You can also use %MAINWEB% instead of Main, but this is not necessary even if you have renamed the main web by configuring $mainWebname in TWiki.cfg.
Configuring Outgoing Mail
TWiki will use the Net::SMTP module if it is installed on your system. Set this with the SMTPMAILHOST variable in TWikiPreferences.
The notify e-mail uses the default changes.tmpl template, or a skin if activated in the TWikiPreferences.
mailnotify also relies on two hidden files in each TWiki/data/[web] directory: .changes and .mailnotify. Make sure both are writable by your web server process. .changes contains a list of changes; go ahead and make this empty. .mailnotify contains a timestamp of the last time notification was done.
You can use an external mail program, like sendmail, if the Net::SMTP module is not installed. Set the program path in $mailProgram in TWiki.cfg.
Net::SMTP can be easily disabled (ex: if there is an installation error) by setting SMTPMAILHOST in TWikiPreferences to an empty value.
You can set a separate SMTPSENDERHOST variable to define the mail sender host (some SMTP installations require this).
Setting the Automatic Email Schedule
For Unix platforms: Edit the cron table so that mailnotify is called in an interval of your choice. Please consult man crontab of how to modify the table that schedules program execution at certain intervals. Example:
The above line will call mailnotify at 15 minutes and 45 minutes past every hour. The -q switch suppresses all normal output.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows NT/2000: You can use a scheduled task if you have administrative privileges.
Note: AT on an NT machine is pretty limited.
Microsoft lists several third-party
replacements
(as of 2001-11-20, none of them free).
WebStatistics Site Usage Log
You can generate a listing manually, or on an automated schedule, of visits to individual pages, on a per web basis. Compiled as a running total on a monthly basis. Includes totals for Topic Views, Topic Saves, Attachment Uploads, Most Popular Topics with number of views, and Top Contributors showing total of saves and attachment uploads. Previous months are saved.
You can automatically generate usage statistics for all webs. To enable this:
Make sure variable $doLogTopicView, $doLogTopicSave and $doLogTopicUpload in TWiki.cfg are set. This will generate log entries in file twiki/data/log<date>.txt .
The WebStatistics topic must be present in all webs where you want to have statistics. You can use the topic in the Main web as a template.
Call the twiki/bin/statistics script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
Attention: The script must run as the same user as the CGI scripts are running, which is user nobody on most systems. Example crontab entry: 0 0 * * * (cd /path/to/TWiki/bin; ./statistics >/dev/null 2>&1)
There is a workaround in case you can't run the script as user nobody : Run the utility twiki/bin/geturl in your cron job and specify the URL of the twiki/bin/statistics script as a parameter. Example: 0 0 * * * (cd /path/to/TWiki/bin; ./geturl mydomain.com /urlpath/to/TWiki/bin/statistics >/dev/null 2>&1)
Generating Statistics Manually by URL
The twiki/bin/statistics script can also be executed as a CGI script, just enter the URL in your browser. Examples:
Update current month for all webs: http://mydomain.com/twiki/bin/statistics
Update current month for Main web only: http://mydomain.com/twiki/bin/statistics/Main
Update January 2000 for Main web: http://mydomain.com/twiki/bin/statistics/Main?logdate=200001
WebSearch
WebSearch is an extremely fast and flexible search facility, part of the core TWiki feature set. Options include:
topic title or full-text search
regular expressions
search within web or site-wide
index-style A-Z alphabetical listing sorted topic title
many more
See also: TWikiVariables for including hard-coded searches in text.
WebChanges
To check for the most recently edited topics while on-site, use the WebChanges link, usually located on the upper toolbar. It lists the most recently modified topics, newest first, along with the first couple of lines of the page content.
This is simply a preset SEARCH. The number of topics listed by the limit parameter.:
Skins overlay regular templates with alternate header/footer layouts; topic text is not affected
Overview
Skins are customized TWikiTemplates files. You can use skins to change the look of a TWiki topic, for example, the layout of the header and footer. Rendered text between header and footer does not change. You can also use skins to define an alternate view, like a view optimized for printing.
Defining Skins
Skin files are located in the twiki/templates directory and are named with the syntax: <scriptname>.<skin>.tmpl. For example, the Printable skin for the view template is view.print.tmpl.
Use the existing TWikiTemplates (like view.tmpl) or skin files as a base for your own skin, name it for example view.myskin.tmpl.
Variables in Skins
You can use template variables, TWikiVariables, and other predefined variables to compose your skins. Some commonly used variables in skins:
Web specific background color, defined in the WebPreferences
%WIKITOOLNAME%
The name of your TWiki site
%SCRIPTURL%
The script URL of TWiki
%SCRIPTSUFFIX%
The script suffix, ex: .pl, .cgi
%WEB%
The name of the current web. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%WEB%"}% for proper handling in an internationalized environment
%TOPIC%
The name of the current topic. Note: It is recommended to URL-encode the variable in form actions with %INTURLENCODE{"%TOPIC%"}% for proper handling in an internationalized environment
%WEBTOPICLIST%
Common links of current web, defined in the WebPreferences. It includes a #GoBox
%TEXT%
The topic text, e.g. the content that can be edited
The %WEBTOPICLIST% includes a "Go" box to jump to a topic. The box also understand URLs, e.g. you can type http://www.google.com/ to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onSelect method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:
Server and client requirements for TWiki 01-Feb-2003
Low client and server requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions.
Server Requirements
TWiki is written in Perl 5, uses a number of shell commands, and requires RCS (Revision Control System), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements.
*Current documentation mainly covers Linux and Apache installations. See WindowsInstallCookbook for a Windows installation guide. See TWiki:Codev.TWikiOn for help with installation on various platforms including Unix, MacOS X, Apache mod_perl, web hosts, etc.
generates XHTML 1.0 pages that are compatible with HTML 3.2
minimal use of JavaScript in the user interface (degrades gracefully)
no cookies
no CSS
You can easily add functionality, by customizing TWikiTemplates, for one, while tailoring the browser requirements to your situation.
Known Issues
The TWikiPlugins feature currently does not have compatibility guidelines for developers. Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
Plugins included in the TWiki distribution do not add requirements.
Definition of the templates used to render all HTML pages displayed in TWiki
Overview
The new modular template system offers flexible, easy control over the layout of all TWiki pages. The master template approach groups parts that are shared by several templates - like headers and footers - in a common file. Special variables allow individual layouts to include parts from a master template - variables are mixed with regular HTML markup for template-specific content. Templates are used to define page layout, and also to supply default content for new pages.
Major changes from the previous template system
Where the old templates were each complete HTML documents, the new templates are defined using variables to include template parts from a master file. You can now change one instance of a common element to update all occurrences; previously, every affected template had to be updated. This simplifies the conversion of templates into XHTML format, and provides a more versatile solution for templates and for TWikiSkins. The new system:
separates a set of common template parts into a base template that is included by all of the related templates;
defines common variables, like a standard separator (ex: "|"), in the base template;
defines variable text in the individual templates and passes it back to the base template.
How Template Variables Work
Special template directives (or preprocessor commands) are embedded in normal templates.
All template preprocessing is done in &TWiki::Store::readTemplate() so that the caller simply gets an expanded template file (the same as before).
Directives are of the form %TMPL:<key>% and %TMPL:<key>{"attr"}%.
Directives:
%TMPL:INCLUDE{"file"}%: Includes a template file. The template directory of the current web is searched first, then the templates root (twiki/templates).
%TMPL:DEF{"var"}%: Define a variable. Text between this and the END directive is not returned, but put into a hash for later use.
%TMPL:END%: Ends variable definition.
%TMPL:P{"var"}%: Prints a previously defined variable.
Variables live in a global name space: there is no parameter passing.
Two-pass processing lets you use a variable before or after declaring it.
Templates and TWikiSkins work transparently and interchangeably. For example, you can create a skin that overloads only the twiki.tmpl master template, like twiki.print.tmpl, that redefines the header and footer.
Use of template directives is optional: templates work without them.
NOTE: Template directives work only for templates: they do not get processed in topic text.
Types of Template
There are three types of template:
Master Template: Stores common parts; included by other templates
HTML Page Templates: Defines the layout of TWiki pages
Template Topics: Defines default text when you create a new topic
Master Templates
Common parts, appearing in two or more templates, can be defined in a master template and then shared by others: twiki.tmpl is the default master template.
Simple header with reduced links (ex: edit, attach, oops)
%TMPL:DEF{"standardfooter"}%
Footer, excluding revision and copyright parts
%TMPL:DEF{"oops"}%
Skeleton of oops dialog
HTML Page Templates
TWiki uses HTML template files for all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.
Templates are in the twiki/templates directory. As an example, twiki/templates/view.tmpl is the template file for the twiki/bin/view script. Templates can be overloaded by individual webs. The following search order applies:
twiki/templates/$webName/$scriptName.tmpl
twiki/templates/$scriptName.tmpl
$webName is the name of the web (ex: Main)
$scriptName is the script (ex: view).
NOTE:TWikiSkins can be defined to overload the standard templates.
Special variables are used in templates, especially in view, to display meta data.
Template Topics
Template topics define the default text for new topics. There are three types of template topic:
All template topics are located in the TWiki web. The WebTopicEditTemplate can be overloaded. When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
A topic name specified by the templatetopic CGI parameter.
WebTopicEditTemplate in the current web
WebTopicEditTemplate in the TWiki web
Edit Template Topics and Variable Expansion
The following variables get expanded when a user creates a new topic based on a template topic:
A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable like %URLPARAM%NOP%{...}%
%NOP{ ... }%
A no-operation text that gets removed. Useful to write-protect an edit template topic, but not the topics based this template topic. See notes below. Example: %NOP{ * Set ALLOWTOPICCHANGE = Main.TWikiAdminGroup }%
Notes:
Unlike other variables, %NOP{ ... }% can span multiple lines.
The scan for the closing }% pattern is "non-greedy", that is, it stops at the first occurance. That means, you need to escape variables with parameters located inside %NOP{ ... }%: Insert a %NOP% between } and %. Silly example: %NOP{ %GMTIME{"$year"}%NOP%% }%.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
Template Topics in Action
Here is an example for creating new topics based on a specific template topic:
The above form asks for a topic name. A hidden input tag named templatetopic specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH%/edit%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%"}%/">
* New example topic:
<input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="23" />
<input type="hidden" name="templatetopic" value="ExampleTopicTemplate" />
<input type="hidden" name="onlywikiname" value="on" />
<input type="submit" value="Create" />
(date format is <nop>YYYYxMMxDD)
</form>
The onlywikiname parameter enforces WikiWords for topic names.
TIP: You can use the %WIKIUSERNAME% and %DATE% variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: -- %WIKIUSERNAME% - %DATE%
Templates by Example
Attached is an example of an oops based template oopsbase.tmpl and an example oops dialog oopstest.tmpl based on the base template. %A% NOTE: This isn't the release version, just a quick, simple demo.
Base template oopsbase.tmpl
The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing %TMPL:P{"sep"}%
Each oops template basically just defines some variables and includes the base template that does the layout work.
%TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
%TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
%TMPL:DEF{"heading"}%
Test heading %TMPL:END%
%TMPL:DEF{"message"}%
Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
* Some more blah blah blah blah blah blah blah blah blah blah...
* Param1: %PARAM1%
* Param2: %PARAM2%
* Param3: %PARAM3%
* Param4: %PARAM4%
%TMPL:END%
%TMPL:DEF{"topicaction"}%
Test =topicaction=:
[[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
[[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
%TMPL:INCLUDE{"oopsbase"}%
Sample screen shot of oopstest.tmpl
With URL: .../bin/oops/Sandbox/TestTopic2?template=oopstest¶m1=WebHome¶m2=WebNotify
Known Issues
A drawback of referring to a master template is that you can only test a template from within TWiki, where the include variables are resolved. In the previous system, each template was a structurally complete HTML document with a .tmpl filename extension - it contained unresolved %VARIABLES%, but could still be previewed directly in a browser.
The basic building block of a TWiki site is called a topic, identified by a unique, hopefully descriptive, WikiWord title. It may seem easier just to call them pages, but specifically a topic is the content of a page. The distinction seems small but will become more important as your skill using TWiki increases. TWikiSites are built using topics.
Characteristics
A TWiki topic is a rich information unit. Each topic has:
name
instantly identify what the topic is about
link to it from other topics just by typing it in it's WikiWord
rename a topic and automatically update all of the links to it, site-wide
move a topic from one TWiki web to another
safely delete a topic to a special Trash web (invisible, but recoverable from the Web server if necessary)
many more features...
The configuration of your TWiki site, skins and your personal user account can modify the way these features are used and presented to you.
Creating and editing topics
A primary purpose of TWiki is to make it incredibly easy for you to add and edit information on existing topics, create new topics, and link between TWiki topics.
To modify a topic: click the Edit link in the toolbar at the bottom left of every page (using the Default skin). An editing window appears. Type away. Use the GoodStyle and TextFormattingRules links to get pop-up window help.
Click Preview Changes to see how your edit looks.
Click Save Changes to save.
To add a new topic: the simplest way is to type a new WikiName in an existing topic, while you're in edit mode. When the topic is saved, the new name will appear highlighted, with a ? at the end: click the ? and a new edit window appears. Enter, preview and save as usual. The new topic now exists.
Go back to the topic where you started, and you'll see the ? has disappeared, and your WikiWord name is now a regular link. Type it anywhere on any topic in that web, and it will be turned into a link.
One little links rule: each topic, and its WikiWord link, belong to one unique web only. To link between webs, you must first enter the topic's web name. Example: This is TWikiTopic?, in the TWiki web, so that's all you need to type on any topic in this web. But to link to TWikiTopics from a topic in the Main web, you have to type TWiki.TWikiTopics - Webname.TopicName. It's easy.
Another way to add a topic is to type a new topic name in the Go box or an unknown topic URL. You can type in either a WikiName to create the topic in the current web or Web.TopicName to create a topic in a different web than the current page. Topics created with the Go box or URLs do not have parent meta-data defined.
Other features
The color-coded toolbar at the bottom of every topic displays a series of links, including:
[Ref-By] - displays all the TWiki topics with links to the current topic
[Diffs] - generates a page showing every change made to the current topic, with names, dates, and changes made (diffs)
r1.3 | > | r1.2(ex) - view most recent revision and changes
[More] - opens up a new screen containing additional controls
It looks complicated, but the basics you need to begin with are very simple to use. The flexible and optional features are ready when you care to learn about them - the only way to confuse yourself or your site set-up and users is by using features you really don't need. Unlike the usual expensive, complex collaboration and project management packages, TWiki is fully functional and effective just by typing in text and making WikiWord links. All the additional features are there, but only if you need them!
Some controls are self-explanatory and also include instructions and help links.
Experiment. You can always Cancel an edit or (using revision control) go Back whenever you like.
Get in-depth info from the complete documentation, including the User's Guide, Configuration Manual and TWiki Reference.
Renaming, moving or deleting topics
You can rename, move and delete individual topics by clicking More on the control strip at the bottom of every page. The access settings for a topic, web or entire site may be disabled for one or more of the three options, depending on your site set-up and access permissions.
Go to the top you want to change, click More > Rename/move
To move or delete: select the target web (Trash to delete)from the pull-down menu (otherwise, leave on the current web)
To rename: fill in a new WikiName (otherwise, leave the current topic name)
To update links: From the list of topics that show links to the topic you're changing, uncheck each entry you DON'T want to update - only checked links will be updated;
Click Rename/move: the topic is renamed and/or moved, and the checked links to the topic are updated.
Any problems are listed - take note, and you can fix them later.
If a linked topic can't be updated (it may be locked because someone's editing it), an alert will appear. You can update missed topics later by again pressing Rename/move.
Deleting means moving a topic to the Trash web. Since all webs share the one Trash, name conflicts may come up.
Reviewing and Reverting
RCS revision control automatically saves all topic changes. To look at earlier versions of a topic, click on Diffs link in topic commands. If you would like to revert to an earlier version or reclaim part of an earlier version, just copy from the old topic revision to the current topic revision. This is a step by step set of instructions:
In the Diffs view, take note of what version of the topic you want to reclaim and then return to View.
Select More in the topic commands.
Under "View previous topic revision," enter the version number you want to reclaim and check "raw text format." Then click on "View revision."
Select either the portion of that version you want to reclaim or the entire text of the topic if you want to revert completely to that version. Select Copy under your browser's Edit menu.
Return to the most recent version of the topic and select Edit from the topic commands.
Either paste in the portion of the topic you wish to reclaimed or replace the entire text with the text you copied from the earlier version.
This step-by-step, hands-on tutorial gets you up to speed with all the TWikiSite basics, in mere minutes...
1. Get set...
Open two browser windows, so that you can follow these steps in one window, while trying things out in the other.
2. Take a quick tour...
A TWikiSite is divided into webs; each one usually represents one area of collaboration. You can navigate the webs from the upper right corner of each web page.
Each web has hyperlinked topics, displayed as pages in your browser.
To browse a TWiki web, just click on any highlighted link. These links are called WikiWords and comprise two or more words with initial capitals, run together.
If you know the name of a topic, you can jump directly to it by typing its name into the Go field on the top of the page. Type WebSearch to jump to the search page. Hint: Do not confuse the Go field with search.
You can search each TWiki web. Enter a search string in the WebHome topic or the WebSearch topic accessible from the Search link on each topic. TWiki searches for an exact match; optionally, you can also use RegularExpressions.
3. Open a private account...
To edit topics, you need to have a TWiki account.
Go to the TWikiRegistration page to create your TWiki account. Fill in a couple of lines and you're set!
4. Check out TWiki users, groups, offices...
Go to the TWikiUsers topic in the TWiki.Main web; it has a list of all users of TWiki. Your WikiName will be in this list after you register.
Go to the TWikiGroups topic in the TWiki.Main web; it has a list of groups which can be used to define fine grained TWikiAccessControl in TWiki.
Go to the OfficeLocations topic in the TWiki.Main web; it has a sample list of corporate offices. This type of set-up can be used for departments, client companies, or any other type of organizational divisions.
5. Test the page controls...
Go to the bottom of the page to see what you can do. The color-coded control strip has a collection of action links:
[Edit] - add to or edit the topic (discussed later)
[Attach] - attach files to a topic (discussed later)
[Ref-By] - find out what other topics link to this topic (reverse link)
[Printable] - goes to a stripped down version of the page, good for printing
[Diffs] - topics are under revision control - [Diffs] shows you the complete change history of the topic, ex: who changed what and when.
[r1.3 | > | r1.2 | > | r1.1] - view a previous version of the topic or the difference between two versions.
[More] - additional controls, like [Rename/move], version control and setting the topic's parent.
6. Change a page, and create a new one...
Go to the Sandbox. This is the sandbox web, where you can make changes and try it all out at will.
Click the [Edit] link. You are now in edit mode and you can see the source of the page. (Go to a different topic like TestTopic3? in case you see a "Topic is locked by an other user" warning.)
Look at the text in edit mode and compare it with the rendered page (move back and forth in your browser.)
Notice how WikiWords are linked automatically; there is no link if you look at the text in edit mode.
Now, create a new topic - your own test page:
In edit mode, enter a new text with a WikiWord, ex: This is YourOwnSandBox topic.
Preview and save the topic. The name appears, highlighted, with a linked question mark at the end. This means that the topic doesn't exist yet.
Click on the question mark. Now you're in edit mode of the new topic.
Type some text, basically, like you write an email.
A signature with your name is already entered by default. NOTE: The Main. in front of your name means that you have a link from the current web to your personal topic located in the Main web.
Preview and save the topic...
Learn about text formatting. You can enter text in TWikiShorthand, a very simple markup language. Follow the TWikiShorthand link to see how, then:
Go back to your sandbox topic end edit it.
Enter some text in TWikiShorthand: bold text, italic text, bold italic text, a bullet list, tables, paragraphs, etc. Hint: If you need help, click on the TextFormattingRules link located below the text box in edit mode.
Preview and save the topic.
7. Use your browser to upload files as page attachments...
You can attach any type of file to a topic - documents, images, programs, whatever - where they can be opened, viewed, or downloaded.
Attaching files is just like including a file with an email.
Go back to your sandbox topic and click on the [Attach] link at the bottom.
Click [Browse] to find a file on your PC that you'd like to attach; enter an optional comment; leave everything else unchecked.
Click [Upload file], then scroll to the end of the page to see the new attachment listing.
Do this again - this time, upload a GIF, JPG or PNG image file.
Check the [Link:] box to Create a link to the attached file at the end of the topic. The image will show up at the bottom of the topic.
To move the image, edit the topic and place the last line (containing %ATTACHURL%) anywhere on the page.
If you have a GIF, JPG or PNG image of yourself, your cat, your sprawling family estate...why not upload it now to personalize your account page: Main.guest?
8. Get email alerts whenever pages are changed...
WebNotify is a subscription service that automatically notifies you by email when topics change in a TWiki web. This is a convenience service - for many people, checking email is easier than checking the Web.
If you're using TWiki to collaborate on a project, it's important to know when anyone on your team posts an update. If you're following a specific discussion, it's convenient to know when there's new input.
Alerts are emailed as links to individual topics that've been changed in a set period: each day, every hour, whatever is configured for your system.
It's strongly recommended that you try out the service by subscribing to each TWiki web that's relevant to you. You can subscribe and unsubscribe instantly, on a per web basis using WebNotify.
That's it! You're now equipped with all the TWiki essentials. You are ready to roll.
NOTE: When first using TWiki, it will probably seem strange to be able to change other people's postings - we're used to separating individual messages, with email, message boards, non-Wiki collaboration platforms. Don't worry about it. You can't accidentally delete important stuff - you can always check previous versions, and copy-and-paste from them if you want to undo any changes. After a short while, TWiki-style free-form communication becomes second-nature. You'll expect it everywhere!
-- MikeMannix? - 01 Dec 2001
Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003
Overview
This guide describes how to upgrade from TWiki 01-Dec-2001 to TWiki 01-Feb-2003. The new version involves several new features and numerous enhancements to the previous version.
Upgrade Requirements
To upgrade from a 01-Dec-2001 standard installation to the latest 01-Feb-2003 TWiki Production Release, follow the instructions below.
To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.
Internationalization ('I18N') support 8-bit character sets in WikiWords, such as ISO-8859-15, KOI8-R
Possible to omit e-mail address in WebNotify, in which case the e-mail is taken from the user's home page; if the WikiName is a group name, a notification is sent to all members of the group
New data storage framework that lets you use external RCS commands for revision control, or a new native Perl implementation that does not depend on the external RCS commands (not recommended yet for production use, see TWiki:Codev/RcsLite)
New AND search; with regular expression enabled, use the semicolon ";" as the AND operator in %SEARCH{}% variable, FormattedSearch and WebSearch
Many more enhancements, see the complete change log at TWikiHistory
Upgrade Procedure from 01-Dec-2001 to 01-Feb-2003 Release
The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Dec-2001 release. As written this will require some downtime. A process for switching over without downtime is described at the end of this section.
Back up and prepare:
Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates, $TWIKIROOT/lib.
Create a temporary directory and unpack the ZIP file there.
Update files in TWiki root:
Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
Update template files:
Overwrite all template files in $TWIKIROOT/templates with the new ones.
If you have customized your templates, make sure to merge those changes to the new files.
If you have customized skins or loaded new skins, make sure to merge or apply those changes to the new files.
Specific changes to templates and skins:
Replace %WIKIHOMEURL% with %WIKILOGOURL%
Replace img tag's src=%PUBURLPATH%/wikiHome.gif with src=%WIKILOGOIMG%
Replace img tag's alt="TWiki Home" with alt="%WIKILOGOALT%"
Replace meta tag's charset=iso-8859-1" with charset=ISO-8859-1"
For internationalized sites, URL encode webs and topics in all form actions, e.g. replace .../view%SCRIPTSUFFIX%/%WEB%/%TOPIC%" with .../view%SCRIPTSUFFIX%/%INTURLENCODE{"%WEB%/%TOPIC%"}%
Update script files:
Overwrite all script files in $TWIKIROOT/bin with the new ones.
If necessary, change the script names to include the required extension, e.g. .cgi
Edit $TWIKIROOT/bin/setlib.cfg and point $twikiLibPath to the absolute file path of $TWIKIROOT/lib
Edit $TWIKIROOT/bin/.htaccess to include a directive for the new manage script: <Files "manage"> require valid-user </Files>
Pay attention to the file and directory permissions, the scripts need to be executable, e.g. chmod 775 $TWIKIROOT/bin/*
If on Non-Unix host, make sure the correct path to the perl interpreter is changed in the first line of every script file. See also WindowsInstallCookbook.
Update library files:
Overwrite the TWiki.cfg configuration file in $TWIKIROOT/lib with the new one.
Restore the configuration values from the backup. You typically need to configure just the ones in the section "variables that need to be changed when installing on a new server".
Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
Copy and overwrite all subdirectories below $TWIKIROOT/lib with the new ones. Make sure to preserve any extra Plugins you might have in $TWIKIROOT/lib/TWiki/Plugins
Pay attention to the file and directory permissions, the library files should not be executable, e.g. chmod -R 664 $TWIKIROOT/lib/*
Update data files:
Run the bin/testenv script from the browser (e.g. http://localhost/bin/testenv) to verify if the cgi-scripts are running as user nobody.
In case not: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g. www-data:
Change the lock user in the temporary twiki/data/* directories where you unzipped the installation package: A simple way to switch the locker of the RCS files is to use sed in the :
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
In the temporary twiki/data/TWiki directory where you unzipped the installation package:
Remove the files you do not want to upgrade: InterWikis.*, TWikiRegistration.*, TWikiRegistrationPub.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
Rename in the temporary directory the file $TWIKIROOT/data/TWiki/TWikiPreferences.* to TWikiPreferencesSave.*.
Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory, overwriting the existing ones.
Merge your original TWikiPreferencesSave.txt settings into $TWIKIROOT/data/TWiki/TWikiPreferences.txt.
Move the data/_default directory from the temporary location to your $TWIKIROOT/data directory.
Move the data/Sandbox directory from the temporary location to your $TWIKIROOT/data directory (The Test web has been renamed to Sandbox in this release.)
There are now two webs in parallel (Test and Sandbox) for the purpose of testing (experimenting) TWiki. Move all relevant topics from Test web to Sandbox web, or motivate the users to do.
Make sure that the directories and files below $TWIKIROOT/data are writable by your cgi-script user.
Adapt the other webs (all other than TWiki and _default):
Merge the new files WebHome.txt and WebPreferences.txt of your other webs to make sure, you have the improvements applied also in your other webs.
Update pub files:
Move all subdirectories below pub/TWiki from your temporary directory into your $TWIKIROOT/pub/TWiki directory.
Make sure that the directories and files below $TWIKIROOT/pub/TWiki are writable by your cgi-script user.
Move all files in pub/icn directory from the temporary location to your $TWIKIROOT/pub/icn directory.
Execute the $TWIKIROOT/bin/testenv script from your browser (e.g. http://localhost/bin/testenv) to see if it reports any issues; fix any potential problems.
Test your updated TWiki installation to see if you can view, create, edit and rename topics; upload and move attachments; register users.
Test if the installed Plugins work as expected. You should see the list of installed Plugins in TextFormattingRules.
Note: These steps assume a downtime during the time of upgrade. You could install the new version in parallel to the existing one and switch over in an instant without affecting the users. As a guideline, install the new version into $TWIKIROOT/bin1, $TWIKIROOT/lib1, $TWIKIROOT/templates1, $TWIKIROOT/data/TWiki1 (from data/TWiki), $TWIKIROOT/pub/TWiki1 (from pub/TWiki), and configure TWiki.cfg to point to the same data and pub directory like the existing installation. Once tested and ready to go, reconfigure $TWIKIROOT/bin1/setlib.cfg and $TWIKIROOT/lib1/TWiki.cfg, then rename $TWIKIROOT/bin to $TWIKIROOT/bin2, $TWIKIROOT/bin1 to $TWIKIROOT/bin. Do the same with the lib, templates and data/TWiki directories.
If you are coming from a version earlier than the 01 May 2000 production release, please see TWikiUpgradeTo01May2000 first. For the latest version read TWikiUpgradeGuide.
The 01 Dec 2000 release has these changes that affect the upgrade of the 01 May 2000 version:
Improved search, i.e. search multiple webs.
The changes script has been retired (related to new search).
Reorganization of topics: The TWiki.Main web was split up into TWiki.Main and TWiki.TWiki web.
This upgrade is somewhat more labor intensive, mainly caused by splitting up the TWiki.Main web. Please note that subsequent updates will be much easier because user related topics (in TWiki.Main web) and TWiki related documents (in TWiki.TWiki web) have been separated.
These are the steps you need to perform to upgrade the 01 May 2000 version to the 01 Dec 2000 release: [ We assume export TWIKIROOT=/some/dir/ ]
Unpack the zip file into some working directory:
mkdir -p ~/tmp/ cd ~/tmp unzip ~/TWiki20001201.zip
Upgrade the TWiki document files ( twiki )
Move the document files to your TWiki root, i.e.
mv ~/tmp/TWiki*.html $TWIKIROOT mv ~/tmp/readme.txt $TWIKIROOT
Upgrade cgi-bin scripts ( twiki/bin )
Rename your original twiki/bin directory, i.e.
mv $TWIKIROOT/bin $TWIKIROOT/bin.old
Move the new scripts to your original twiki/bin location, i.e.
mv ~/tmp/bin $TWIKIROOT/bin
Merge the changes in your current wikicfg.pm into the new wikicfg.pm. We suggest using diff -c to compare the two files if you have made heavy changes to the file, i.e.
diff -c $TWIKIROOT/bin.old/wikicfg.pm $TWIKIROOT/bin/wikicfg.pm | less
Restore any additional scripts you might have from the old directory, i.e.
mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/ (Note that the changes script is obsolete.)
In case you have basic authentication:
The TWikiRegistration topic moved from the TWiki.Main web to the TWiki.TWiki web. Change .htaccess to reflect the new location, i.e.
ErrorDocument 401 /cgi-bin/view/TWiki/TWikiRegistration
Pay attention to the file and directory permissions (security issue)
Test your TWiki installation if you can view topics. (Ignore the %HTTP_EQUIV_ON_VIEW% you see on top of the topic; this will disappear after upgrading the template files.
Upgrade template files ( twiki/templates )
Rename your original twiki/templates directory, i.e.
mv $TWIKIROOT/templates $TWIKIROOT/templates.old
Move the new templates to your original twiki/templates location, i.e.
mv ~/tmp/templates $TWIKIROOT/templates
Merge the changes in your current template files into the new template files. To compare two files use
diff -c $TWIKIROOT/templates.old/view.tmpl $TWIKIROOT/templates/view.tmpl | less
Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
Test your TWiki installation if you can view topics.
Upgrade public files ( twiki/pub )
Move the new twiki/pub/TWiki directory to your installation, i.e.
mv ~/tmp/pub/TWiki $TWIKIROOT/pub/
Pay attention to the file permissions of the TWiki directory and its subdirectory and files. The files must be writable by the cgi-scripts (usually user "nobody")
Move the new twiki/pub/twikilogo* image files to your installation, i.e.
mv ~/tmp/pub/twikilogo* $TWIKIROOT/pub/
Upgrade data files ( twiki/data )
Move the new twiki/data/TWiki directory to your installation, i.e.
mv ~/tmp/data/TWiki $TWIKIROOT/data/ Pay attention to the file permissions of the TWiki directory and its files. The files must be writable by the cgi-scripts (usually user "nobody")
Optionally move the new twiki/data/Test directory to your installation, i.e.
mv ~/tmp/data/Test $TWIKIROOT/data/ (Pay attention to the file permissions)
Move these new TWiki.Main web topics to your TWiki.Main web: TWikiGroups, TWikiAdminGroup, and if needed also OfficeLocations , i.e.
mv ~/tmp/data/Main/TWikiGroups.* $TWIKIROOT/data/Main (Pay attention to the file permissions)
The following topics in the TWiki.Main web are obsolete and can be deleted: BillClinton, GoodStyle, RegularExpression, TextFormattingFAQ, TextFormattingRules, ManagingWebs, TWikiCategoryTable, TWikiEnhancementRequests, TWikiImplementationNotes, TWikiInstallationGuide, WebNotification, TWikiPlannedFeatures, TWikiUpgradeTo01May2000, TWikiUsernameVsLoginUsername, TWikiSite, WelcomeGuest, WelcomeVisitor, WikiName, WikiNotation, WikiTopic, WikiWikiClones. Sample delete command:
rm -f $TWIKIROOT/data/Main/BillClinton.*
The following topics are new and most be copied to all of your TWiki webs: WebChanges, WebIndex.
cp -p $TWIKIROOT/data/TWiki/WebChanges.txt* $TWIKIROOT/data/Main cp -p $TWIKIROOT/data/TWiki/WebIndex.txt* $TWIKIROOT/data/Main Repeat this for all your webs. Pay attention to the file permissions.
TWikiRegistration moved from TWiki.Main to TWiki.TWiki. In case you customized TWikiRegistration , merge your changes back into TWiki.TWikiRegistration , then delete $TWIKIROOT/data/Main/TWikiRegistration*.
TWikiPreferences moved from TWiki.Main to TWiki.TWiki. Merge your changes to TWikiPreferences into TWiki.TWikiPreferences.
Modify the WebPreferences topics in all your webs to reflect the following:
WEBTOPICLIST should use WebChanges for "Changes", and WebIndex for "Index", i.e.
| <a href="WebChanges">Changes</a> | <a href="WebIndex">Index</a>
In case you want to exclude a web from a web="all" search: Set this new preference
Set NOSEARCHALL = on
The WebSearch topic has considerable changes. Copy the one from TWiki.TWiki into all webs, or merge them if you made changes. To copy, do an edit-copy-edit-paste operation.
Change the WebHome topics in all your webs to reflect these changes:
The "Changes" link should point to WebChanges.
The "Topic index" link should point to WebIndex.
Change the include of the web table to %INCLUDE{"%TWIKIWEB%.TWikiWebsTable"}%
Merge your TWikiWebsTable topic in TWiki.Main with the TWikiWebsTable topic in TWiki.TWiki. Note the new variable to query the color of a web. Delete the old TWikiWebsTable topic in TWiki.Main after merge is complete.
The following topics in the TWiki.Main web are deprecated (because they moved to TWiki.TWiki), but still need to be present in TWiki.Main because of existing links to them: FileAttachment, TWikiDocumentation, TWikiHistory, TWikiPreferences, TWikiVariables.
It is recommended that you edit these topics in TWiki.Main and replace the content with this line:
This topic moved to %TWIKIWEB%.%TOPIC% in the %WIKITOOLNAME%.%TWIKIWEB% web.
In all your webs, change references to topics that moved to the TWiki.TWiki web:
Change topics: TWikiUsers , WebNotify , WebHome
With links to: TWikiPreferences , TWikiVariables , TWikiUsers , TWikiWebsTable and WelcomeGuest
TWiki Access Control
Read TWikiAccessControl, in case you want to use the new authorization feature based on groups.
Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release)
This guide describes how to upgrade either from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001.
The latest version of TWiki (01-Dec-2001) is a small incremental release over the 01-Sep-2001 version.
The 01-Sep-2001 version involves several major new features and numerous enhancements to the last full version (01-Dec-2000). The file system set-up is almost identical, but much of the underlying data structure and processes is new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly.
Upgrade Requirements
To upgrade from a 01-Dec-2000 or 01-Sep-2001 standard installation to the latest 01-Dec-2001 TWiki Production Release, follow the instructions below.
To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.
Major Changes from TWiki 01-Sep-2001
The latest 01-Dec-2001 release includes the following new features and enhancements compared to the 01-Sep-2001 release:
FormattedSearch - New format="" parameter in %SEARCH{}% variable for database like reporting.
Various bug fixes
Major Changes from TWiki 01-Dec-2000
The 01-Sep-2001 release includes the following new features and enhancements compared to the 01-Dec-2000 release:
TWikiPlugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
InterwikiPlugin (preinstalled) - Link to external sites with text aliases, SiteAlias:Page; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.)
SuperAdministrator Group - Lets you to make the members of one user group - by default, TWikiAdminGroup - into TWiki superusers, with the ability to overwrite locked topics from the browser interface. (This gets around the problem of topic lockouts, caused by typos in access privilege definitions.)
HierarchicalNavigation uses new Meta Data variables to link hierarchically.
Convert to XHTML - Pages are rendered for display in XHTML 1.0, as far as possible without breaking HTML 3.2 compliance.
TWiki Directory Structure and File Names
The TWiki directory structure remains the same, with one exception, the TWiki configuration file and Perl modules have been moved from the twiki/bin directory into it's own twiki/lib directory tree. The following files have been renamed and moved:
A new twiki/lib/TWiki/Plugins directory contains the new Plugin modules.
Standard Upgrade Procedure from 01-Sep-2001 to 01-Dec-2001 Release
This incremental update can be performed easily.
The following steps describe the upgrade assuming that $TWIKIROOT is the root of your current 01-Sep-2001 release.
Back up and prepare:
Back up all existing TWiki directories $TWIKIROOT/bin, $TWIKIROOT/pub, $TWIKIROOT/data, $TWIKIROOT/templates.
Create a temporary directory and unpack the ZIP file there.
Update files in TWiki root:
Overwrite all *.html and *.txt files in $TWIKIROOT with the new ones.
Update template files:
Overwrite all template files in $TWIKIROOT/templates with the new ones.
Update script files:
Overwrite all script files in $TWIKIROOT/bin with the new ones.
Update library files:
Overwrite the TWiki.pm library in $TWIKIROOT/lib with the new one.
Overwrite all *.pm library files in $TWIKIROOT/lib/TWiki and $TWIKIROOT/lib/TWiki/Plugins with the new ones.
Update data/TWiki files: (in case you want the updated docs)
Using your browser, merge the new TWikiRegistrationPub topic (or TWikiRegistrationPubPub in case you used that one) into your existing TWikiRegistrationPub topic.
In the temporary twiki/data/TWiki directory where you unzipped the installation package:
Remove the files you do not want to upgrade: TWikiPreferences.*, WebNotify.*, WebPreferences.*, WebStatistics.* and all WebTopic* files.
In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g., www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Move all remaining *.txt and *.txt,v files from the temporary data/TWiki directory to your $TWIKIROOT/data/TWiki directory.
Update pub/TWiki files:
Move the new pub/TWiki/TWikiDocGraphics directory into your $TWIKIROOT/pub/TWiki directory.
Standard Upgrade Procedure from 01-Dec-2000 to 01-Dec-2001 Release
The idea is to have the new and old installation work in parallel so that you can test the new installation before switching over. That way you can make the switch on your live TWiki installation within one minute without affecting the users.
Before Switch:
After Switch:
Current 01-Dec-2000:
New 01-Dec-2001:
Obsolete 01-Dec-2000:
New 01-Dec-2001:
twiki/templates/
twiki/templates2/
twiki/templates1/
twiki/templates/
twiki/bin/
twiki/bin/2/
(overwritten)
twiki/bin/
(N/A)
twiki/bin/lib/
(N/A)
twiki/lib/
twiki/data/TWiki
twiki/data/TWiki2
twiki/data/TWiki1
twiki/data/TWiki
(other directories do not change)
Alternatively you could move the existing installation away, install the 01-Dec-2001 release into it's place and move your webs and pub files back.
Follow this step-by-step guide to upgrade from the 01-Dec-2000 TWiki to the 01-Dec-2001 release, importing your original page data and related files:
Pre-Upgrade Preparation
Two major areas of TWiki functionality - TWikiTemplates and TWikiForms (input forms associated with a topic)- are entirely different in the new TWiki. If you've customized your templates or use Category Tables, read those sections before starting your upgrade.
The following steps describe the upgrade on Unix. Windows setup is very similar. It's assumed that $TWIKIROOT is the root of your current 01-Dec-2000 release, ex: export TWIKIROOT=/some/dir/
Step 1: Backup & Unpack
Back up all existing TWiki directories twiki/bin, twiki/pub, twiki/data, twiki/templates.
Create a temporary directory and unpack the ZIP file there:
mkdir -p ~/tmp/ cp -p ~/downloads/TWiki20011201.zip ~/tmp/ cd ~/tmp/ unzip ~/tmp/TWiki20011201.zip
Step 2: Upgrade TWiki document files
Move the document files to your TWiki root ( twiki ):
mv ~/tmp/TWiki*.html $TWIKIROOT mv ~/tmp/index.html $TWIKIROOT mv ~/tmp/readme.txt $TWIKIROOT mv ~/tmp/license.txt $TWIKIROOT
Step 3: Install new template files
Move & rename the template directory to a temporary twiki/templates2 directory, ex:
mv ~/tmp/templates $TWIKIROOT/templates2
Pay attention to the file and directory permissions (security issue). Set file permissions, ex:
chmod 644 *.cgi
Step 4: Install new data and pub files
Move the TWiki web to a temporary TWiki2 twiki/data/TWiki2 directory. Do the same to files attached to this web, ex:
mv ~/tmp/data/TWiki $TWIKIROOT/data/TWiki2 mv ~/tmp/pub/TWiki $TWIKIROOT/pub/TWiki2
Move & rename the Know web to a temporary twiki/data/Know2 directory, ex:
mv ~/tmp/data/Know $TWIKIROOT/data/Know2 mv ~/tmp/pub/Know $TWIKIROOT/pub/Know2
Move the _default and Trash web, ex:
mv ~/tmp/data/_default $TWIKIROOT/data mv ~/tmp/data/Trash $TWIKIROOT/data
Move the MIME types file, ex:
mv ~/tmp/data/mime.types $TWIKIROOT/data
Move the TWiki logo files, ex:
mv ~/tmp/pub/*.gif $TWIKIROOT/pub
Pay attention to the file permissions of the TWiki2 and Know2 directories and its files. The files must be writable by the cgi-scripts (usually user nobody).
In case the cgi-scripts are not running as user nobody: The *,v RCS repository files delivered with the installation package are locked by user nobody and need to be changed to the user of your cgi-scripts, e.g., www-data. A simple way to switch the locker of the RCS files is to use sed:
for f in *,v; do sed 's/nobody\:/www-data\:/' $f > x; mv x $f; done
Step 5: Install new CGI scripts
Move & rename the CGI script directory to a temporary twiki/bin/2 directory, ex:
mv ~/tmp/bin $TWIKIROOT/bin/2
If necessary, change the script names to include the required extension, ex: .cgi
Copy any additional scripts you might have from the 01-Dec-2000 release, ex:
cp -p $TWIKIROOT/bin/somescript $TWIKIROOT/bin/2
In case you use basic authentication, rename .htaccess.txt to .htaccess and customize it, ex:
cd $TWIKIROOT/bin/2 mv .htaccess.txt .htaccess diff ../.htaccess . and merge the content
Pay attention to the file and directory permissions (security issue). Set permissions, ex:
chmod 755 *.cgi
Step 6: Install new Perl library files
Move the lib directory to a temporary twiki/bin/lib directory, ex:
mv ~/tmp/lib $TWIKIROOT/bin
Pay attention to the file and directory permissions (security issue). Set permissions, ex:
chmod 644 *.pm
Step 7: Set configurations and test installation
Merge the content of the old twiki/bin/wikicfg.pm into the new twiki/lib/TWiki.cfg configuration file. Use the diff command to find out the differences, ex:
cd $TWIKIROOT/bin/lib diff ../wikicfg.pm TWiki.cfg
Make sure to set the correct temporary location of templates and scripts, ex:
$scriptUrlPath = "/twiki/bin/2"; $templateDir = "/home/httpd/twiki/templates2";
Do not merge the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE, extendGetRenderedVersionInsidePRE from the old twiki/bin/wikicfg.pm. This is now handled by the Default plugin twiki/lib/TWiki/Plugins/Default.pm
Test your new TWiki installation to see if you can view topics. Point your browser to the old installation and fix the URL to see the new installation, ex:
Old URL: http://localhost/cgi-bin/view
New URL: http://localhost/cgi-bin/2/view
Step 8: Update topics
You can do the following changes using your old TWiki 01-Dec-2000 or new TWiki 01-Dec-2001 installation. Pointing your browser to the old installation for edit-copy-edit-paste operations is recommended, so that users don't get surprised by meta data content showing up in topics.
Remember that you now have two TWiki webs:
The original TWiki web.
The new TWiki2 web, which gets renamed to TWiki when you switch over the installation.
In case you customized TWikiRegistrationPub, merge your changes back into TWiki2.TWikiRegistration.
Copy to TWiki2 any topics that you created in the TWiki web.
Do the same for
In TWiki2.TWikiPreferences, merge the old TWiki.TWikiPreferences settings and customize it.
Add your webs to WIKIWEBLIST
Set the WIKIWEBMASTER
Set the SMTPMAILHOST
In WebPreferences of all webs, add or change the following web preferences: (see TWiki.WebPreferences)
Add a NOSEARCHALL in case you want to exclude the web from a web="all" search:
* Set NOSEARCHALL = on
In WEBTOPICLIST, remove the %WEB% . {} decoration from the list (it is now in the templates), ex:
* Set WEBTOPICLIST = <a href="WebHome">Home</a> | <a href="WebChanges">Changes</a> | <a href="WebIndex">Index</a> | <a href="WebSearch">Search</a> | Go <input type="text" name="topic" size="16" />
Add a these new preferences:
* Set DENYWEBVIEW = * Set ALLOWWEBVIEW = * Set DENYWEBRENAME = * Set ALLOWWEBRENAME =
Set the FINALPREFERENCES:
* Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
Optional: In WebSearch of all webs, replace content with this one line:
%INCLUDE{"%TWIKIWEB%.WebSearch"}%
Optional: In WebChanges of all webs, replace content with this one line:
%INCLUDE{"%TWIKIWEB%.WebChanges"}%
Step 9: Customize template files
NOTE: Skip this step if you did not customize your template files.
Remember that you have now two template directories:
The original twiki/templates.
The new twiki/templates2, which gets renamed to twiki/templates when you switch over the installation.
Customized templates and skins need to be upgraded to the new TWikiTemplates. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
Templates are now rendered by TWiki. You can use all TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a =<p /> tag added.
Create a replacement WebForm topic based on twikicatitems.tmpl in each web that uses a Category Table. See details in TWikiForms and compare with the settings in the Know2.WebPreferences topic.
Do not remove the twikicatitems.tmpl file, it is still used for topics that are of the old format.
Searches need to be adjusted to deal with format change. It is possible to define a regular expression search that can deal at the same time with topics in the old format and new format.
Example: List all topics in the Know web that have a TopicClassification of PublicFAQ: %SEARCH{ "[T]opicClassification.*?(td..td|value\=).*?[P]ublicFAQ" casesensitive="on" regex="on" nosearch="on" web="Know"}% (The [T] and [P] is done so that search does not find the topic where this search string is located in!)
Example: Create a link that lists all topics in the Know web with a TopicClassification of PublicFAQ: [[%SCRIPTURL%/search%SCRIPTSUFFIX%/Know/?scope=text &search=%5BT%5DopicClassification.*%3F%28td..td%7C value%5C%3D%29.*%3F%5BP%5DublicFAQ®ex=on][All Public FAQ]] All Public FAQ
For each web that has a custom notedited.tmpl template, create an equivalent WebTopicEditTemplate to conform with the new TemplateTopics. The new format replaces the notedited.tmpl, notext.tmpl and notwiki.tmpl templates.
Step 10: Switch over to new installation
In this step, you move the working 01-Dec-2001 installation to the old 01-Dec-2000 installation, so that users don't have to change the URL.
Test your new 01-Dec-2001 installation under twiki/bin/2/view to make sure everything works as expected.
NOTE: Don't worry about the Plugins, they'll work after the switch.
Edit $TWIKIROOT/bin/lib/TWiki.cfg and remove the /2 from $scriptUrlPath and $templateDir, ex:
$scriptUrlPath = "/twiki/bin"; $templateDir = "/home/httpd/twiki/templates";
Rename the TWiki2 web to TWiki, including attachments, ex:
cd $TWIKIROOT/data mv TWiki TWiki1 mv TWiki2 TWiki cd $TWIKIROOT/pub mv TWiki TWiki1 mv TWiki2 TWiki
Rename the templates2 directory to templates, ex:
cd $TWIKIROOT mv templates templates1 mv templates2 templates
Move the lib directory one level up from $TWIKIROOT/bin/lib to $TWIKIROOT/lib, ex:
cd $TWIKIROOT mv bin/lib .
Copy content of bin/2 to bin, ex:
cd $TWIKIROOT/bin cp -p bin/2/* . cp -p bin/2/.htaccess .
Point your browser to the original URL and make sure the relocated 01-Dec-2001 installation works as expected: check browsing, searching and user registration.
The EmptyPlugin, DefaultPlugin, and InterwikiPlugin should be preinstalled. To check the InterwikiPlugin, go to its page.
If you have customized the functions extendHandleCommonTags, extendGetRenderedVersionOutsidePRE and extendGetRenderedVersionInsidePRE in twiki/bin/wikicfg.pm:
Merge those changes back into twiki/lib/TWiki/Plugins/Default.pm
General Format Changes
The format of the %GMTIME{"..."}% and %SERVERTIME{"..."}% variables is now "$hour:$min" instead of "hour:min". More in TWikiVariables.
ExtendingTableSyntax: Enhanced table syntax might have unwanted side effect: | *bold* | cells, | center aligned | and | right aligned | cells, span multiple columns using | empty cells |||. More in TextFormattingRules.
Use Net::SMTP module instead of sendmail if installed.
Use <verbatim> ... </verbatim> tags instead of <pre> ... </pre> tags where appropriate. More in TextFormattingRules.
New variable %STARTINCLUDE% and %STOPINCLUDE% variables to control what gets included of a topic. More in TWikiVariables.
Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.
Attachments are now under revision control: $attachAsciiPath in TWiki.cfg defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.
Handling for topic-specific templates like edit.new.tmpl has been removed and replaced by template topics in the new TWikiTemplates.
A new file warning.txt file can appear in the data directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.
To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things:
Back up your system.
Update the templates in the /templates directory (and its subdirs):
Take the templates of the latest distribution as the base and merge your changes back into it.
Update the Perl scripts in the /bin directory:
Take the scripts of the latest distribution as the base and merge your changes back into it. Do so also for wikicfg.pm because it has important changes as well.
Update topics:
Copy the new Main. TWikiPreferences? topic (and *,v file) into your TWiki.Main web. Customize the topic to your needs.
In case you are on an Intranet: Copy topic TWikiRegistration to Main.TWikiRegistration. Customize if needed.
In case you are on a public server: Copy topic TWikiRegistrationPub to Main.TWikiRegistration. Customize if needed.
Copy the Main. TWikiWebsTable topic (and *,v file) into your Main web and customize it. Reason: The new release does not use the *.inc include files anymore.
Optionally: Search for %INCLUDE%'s in all your webs and change them to the new %INCLUDE{"file.ext"}% syntax. Note: Your old %INCLUDE:"file.ext"% syntax still works (the legacy rule is defined in wikicfg.pm .)
TWiki site access control and user activity tracking options
TWiki does not authenticate users internally, it depends on the REMOTE_USER environment variable. This variable is set when you enable Basic Authentication (.htaccess) or SSL "secure server" authentication (https protocol).
TWiki uses visitor identification to keep track of who made changes to topics at what time and to manage a wide range of personal site settings. This gives a complete audit trail of changes and activity.
Authentication Options
No special installation steps are required if the server is already authenticated. If it isn't, you have three standard options for controlling user access:
Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki mode. All visitors are assigned the TWikiGuest default identity, so you can't track individual user activity.
Use SSL (Secure Sockets Layer; HTTPS) to authenticate and secure the whole server.
Use Basic Authentication (.htaccess) to control access by protecting key scripts: attach, edit=, installpasswd, preview, rename, save, upload using the .htaccess file. The TWikiInstallationGuide has step-by-step instructions.
Partial Authentication
Tracking by IP address is an experimental feature, enabled in lib/TWiki.cfg. It lets you combine open access to some functions, with authentication on others, with full user activity tracking:
Normally, the REMOTE_USER environment variable is set for the scripts that are under authentication. If, for example, the edit, save and preview scripts are authenticated, but not view, you would get your WikiName in preview for the %WIKIUSERNAME% variable, but view will show TWikiGuest instead of your WikiName.
TWiki can be configured to remember the IP address/username pair whenever an authentication happens (edit topic, attach file). Once remembered, the non-authenticated scripts, like view, will show the correct username instead of TWikiGuest.
Enable this feature by setting the $doRememberRemoteUser flag in TWiki.cfg. TWiki then persistently stores the IP address/username pairs in the file, $remoteUserFilename, which is "$dataDir/remoteusers.txt" by default.
This approach can fail if the IP address changes due to dynamically assigned IP addresses or proxy servers.
Quick Authentication Test - Use the %WIKIUSERNAME% variable to return your current identity:
You are Main.guest
TWiki Username vs. Login Username
This section applies only if your TWiki site is installed on a server that is both authenticated and on an intranet.
TWiki internally manages two usernames: Login Username and TWiki Username.
Login Username: When you login to the intranet, you use your existing login username, ex: pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable, and used internally. Login Usernames are maintained by your system administrator.
TWiki Username: Your name in WikiNotation, ex: PeterThoeny, is recorded when you register using TWikiRegistration; doing so also generates a personal home page in the Main web.
TWiki can automatically map an Intranet (Login) Username to a TWiki Username, provided that the username pair exists in the TWikiUsers topic. This is also handled automatically when you register.
In the original TWiki distribution, in twiki/data, there are two registration form topics, TWikiRegistration and TWikiRegistrationPub?. The original form includes an intranet Login Username field. For Basic Authentication, the original form is replaced by the Pub version. If you started using TWiki on Basic Authentication and want to change, you have to switch back forms for future use, and manually correct the existing entries, by editing TWikiUsers, adding the Login Username for each member - PeterThoeny - pthoeny - 01 Jan 1999 - and also in the .htpasswd file, where you can either replace the WikiNames or duplicate the entries and have both, so both usernames will work. verification and clearer rewrite to follow in a bit. also link to original installation mention.
NOTE:To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces. Ex:
Main.WikiUsername or %MAINWEB%.WikiUsername
This points WikiUser to the TWiki.Main web, where user registration pages are stored, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic? everywhere but in the Main web.
Changing Passwords
Change and reset passwords using forms on regular pages. Use TWikiAccessControl to restrict use as required.
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you.
After submitting this form your password will be changed.
Request for reset of password
Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank you.
After submitting this form you will see a page with your new password appearing encrypted.
This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet.
TWiki internally manages two usernames: Login username and TWiki username.
Login username: When you login to the intranet, you use your existing login username, for example pthoeny. This name is normally passed to TWiki by the REMOTE_USER environment variable. TWiki uses this name internally to log topic changes. Login usernames are maintained by your system administrator.
TWiki username: This is your name in WikiNotation, for example PeterThoeny, recorded when you register in TWikiRegistration; doing so also generates your personal home page in the Main web of your TWiki site.
TWiki can map the intranet username to the Wiki username automatically, provided that the Login username and Wiki username pair has been entered in the TWikiUsers topic. This happens automatically when you register.
NOTE:To correctly enter a WikiName - your own or someone else's - be sure to specify the Main web in front of the Wiki username: write Main.WikiUsername or %MAINWEB%.WikiUsername. This assures that the name will be linked automatically to the Main web, where user home pages are stored, even if the text is entered in a different web.
Special text strings expand on the fly to display user data or system info
TWikiVariables are text strings - %VARIABLE% - that expand into content whenever a page is opened. When a topic is rendered for viewing, VARIABLES are replaced by data, either user-entered, or info automatically generated by TWiki (like the date, or the current username). There are predefined variables, and Preference variables that you configure. You can also define custom variables, with new names and values.
Predefined Variables
Most predefined variables return values that were either set in the lib/twiki.cfg file, when TWiki was installed, or taken from server info (like current username, or date and time). Many of the variables let you format the appearance of the display results.
Take the time to thoroughly read through ALL preference variables. If you actively configure your site, review variables periodically. They cover a wide range of functions, and it can be easy to miss the one perfect variable for something you have in mind. For example, see %INCLUDINGTOPIC%, %INCLUDE%, and the mighty %SEARCH%.
This version of TWiki - 04 Sep 2004 $Rev: 1742 $ - expands the following variables (enclosed in % percent signs):
Variable:
Expanded to:
%WIKIHOMEURL%
The base script URL of TWiki, is the link of the Home icon in the upper left corner, is http://your.domain.com/twiki
%SCRIPTURL%
The script URL of TWiki, is http://wiki.arch.ethz.ch/caadtwiki/bin
%SCRIPTURLPATH%
The path of the script URL of TWiki, is /caadtwiki/bin
%SCRIPTSUFFIX%
The script suffix, ex: .pl, .cgi is
%PUBURL%
The public URL of TWiki, is http://wiki.arch.ethz.ch/caadtwiki/pub Example: You can refer to a file attached to another topic as %PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
The path of the public URL of TWiki, is /caadtwiki/pub
%ATTACHURL%
The attachment URL of the current topic, is http://wiki.arch.ethz.ch/caadtwiki/pub/TWiki/TWikiVariables Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
%ATTACHURLPATH%
The path of the attachment URL of the current topic, is /caadtwiki/pub/TWiki/TWikiVariables
%URLPARAM{"name"}%
Returns the value of a URL parameter. Note that there is a low risk that this variable could be misused for cross-scripting. Ex: %URLPARAM{"skin"}% returns print for a .../view/TWiki/TWikiVariables?skin=print URL. Is
%URLENCODE{"string"}%
Encodes a string for use as a URL parameter. Ex: %URLENCODE{"spaced name"}% returns spaced%20name
%WIKITOOLNAME%
The name of your TWiki site - TWiki
%WIKIVERSION%
Your current TWiki version - 04 Sep 2004 $Rev: 1742 $
%USERNAME%
Your login username - guest
%WIKINAME%
Your Wiki username. Same as %USERNAME% if not defined in the TWikiUsers topic. Is guest
%WIKIUSERNAME%
Your %WIKINAME% including the Main web name - always use full signatures - Main.guest
The index topic of all registered users - TWikiUsers
%WIKIPREFSTOPIC%
The site-wide preferences topic - TWikiPreferences
%WEBPREFSTOPIC%
The local web preferences topic in each web - WebPreferences
%STATISTICSTOPIC%
The web statistics topic WebStatistics
%TOPIC%
The current topic name - TWikiVariables
%BASETOPIC%
The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE.
%INCLUDINGTOPIC%
The name of the topic that includes the current topic. Same as %TOPIC% in case there is no include.
%SPACEDTOPIC%
The current topic name with added spaces, for regular expression search of Ref-By, is TWiki%20*Variables
%TOPICLIST{"format"}%
Topic index of a web. The "format" defines the format of one topic item. It may include variables: The $name variable gets expanded to the topic name; the $web variable gets expanded to the name of the web.
Parameters are format, separator and web:
Format of one line, may include $name and $web variables
"$name"
format="format"
(Alternative to above)
"$name"
separator=", "
line separator
"\n" (new line)
web="Name"
Name of web
Current web
Examples:
%TOPICLIST{" * $web.$name"}% creates a bullet list of all topics.
%TOPICLIST{separator=", "}% creates a comma separated list of all topics.
%TOPICLIST{" <option>$name</option>"}% creates an option list (for drop down menus).
%WEBLIST{"format"}%
Web index, ex: list of all webs. Hidden webs are excluded, e.g. webs with a NOSEARCHALL=on preference variable. The "format" defines the format of one web item. The $name variable gets expanded to the name of the web, $qname gets expanded to double quoted name, $marker to marker where web matches selection.
Parameters are format, separator and web:
comma sep list of Web, public expands to all non-hidden
"public"
marker="selected"
Text for $marker where item matches selection, otherwise equals ""
"selected"
selection="%WEB%"
Current value to be selected in list
section="%WEB%"
Examples: %WEBLIST{" * [[$name.WebHome]]"}% creates a bullet list of all webs.
%WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash,public" selection="TWiki" separator=" "}% Dropdown of all public Webs + Trash Web, current Web highlighted.
If present in included topic, start to include text from this location up to the end, or up to the location of the %STOPINCLUDE% variable. A normal view of the topic shows everyting exept the %STARTINCLUDE% variable itself.
%STOPINCLUDE%
If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the %STOPINCLUDE% variable itself.
%TOC%
Table of Contents of current topic.
%TOC{"SomeTopic" ...}%
Table of Contents. Shows a TOC that is generated automatically based on headings of a topic. Headings in WikiSyntax ("---++ text") and HTML ("<h2>text</h2>") are taken into account. Any heading text after "!!" is excluded from the TOC; for example, write "---+!! text" if you do not want to list a header in the TOC. Parameters are topic name, web and depth:
Search term. Is a regular expression or literal, depending on the regex parameter. For regular expressions ";" is used to mean and e.g. "search;agrep" will find all topic containing search and agrep.
required
search="text"
(Alternative to above)
N/A
web="Name" web="Main Know" web="all"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs. [2]
Current web
scope="topic" scope="text"
Search topic name (title) or in the text (body) of the topic
Custom format results: see FormattedSearch for usage, variables & examples
Results in table
Regular example: %SEARCH{"wiki" web="Main" scope="topic"}%
Formatted example: %SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"%(displays results in a table with header - details) If the TWiki:Plugins.TablePlugin is installed, you may set a %TABLE{}% variable just before the %SEARCH{}% to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children
required
web="%WEB%"
Wiki web to search: A web, a list of webs separated by whitespace, or all webs.
required
topic="%TOPIC%"
The topic the search relates to
required
title="Title"
Text that is prepended to any search results
required
Example: %METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%, you may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate %METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%VAR{"NAME" web="Web"}%
Get a preference value from a web other then the current one. Example: To get %WEBBGCOLOR% of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%, is #FFFFC0
[1] Note: The search form uses identical names for input fields.
[2] Note: A web can be excluded from a web="all" search if you define a NOSEARCHALL=on variable in its WebPreferences.
Preferences Variables
Additional variables are defined in the preferences ( site-level ( SL ) in TWikiPreferences, web-level ( WL ) in WebPreferences of each web, and user level ( UL ) preferences in individual user topics):
Variable:
Level:
What:
%WIKIWEBMASTER%
SL
Webmaster email address (sender of email notifications) , is caad-yearly@hbt.arch.ethz.ch
%WIKIWEBLIST%
SL
List of TWiki webs (in upper right corner of topics)
%WEBTOPICLIST%
WL
Common links of web (second line of topics)
%WEBCOPYRIGHT%
SL , WL
Copyright notice (bottom right corner of topics)
%WEBBGCOLOR%
WL
Background color of web
%NOSEARCHALL%
WL
Exclude web from a web="all" search (set variable to on for hidden webs)
%NEWTOPICBGCOLOR%
SL , UL
Background color of non existing topic. ( UL needs authentication for topic views )
%NEWTOPICFONTCOLOR%
SL , UL
Font color of non existing topic. ( UL needs authentication for topic views )
%EDITBOXWIDTH%
SL , UL
Horizontal size of edit box, is 70
%EDITBOXHEIGHT%
SL , UL
Vertical size of edit box, is 15
%RELEASEEDITLOCKCHECKBOX%
SL , UL
Default state of the "Release edit lock" (UnlockTopic) check box in preview. Checkbox is initially checked if Set RELEASEEDITLOCKCHECKBOX = checked="checked", or unchecked if empty. If checked, make sure to click on Edit to do more changes; do not go back in your browser to the edit page, or you risk that someone else will edit the topic at the same time! Value is: checked
%DONTNOTIFYCHECKBOX%
SL , UL
Default state of the "Minor Changes, Don't Notify" (DontNotify) check box in preview. Check box is initially checked if Set DONTNOTIFYCHECKBOX = checked="checked", or unchecked if empty. Value is: checked
%ATTACHLINKBOX%
SL , UL
Default state of the link check box in the attach file page. Check box is initially checked if value is set to CHECKED , unchecked if empty. If checked, a link is created to the attached file at the end of the topic. Value is:
%HTTP_EQUIV_ON_VIEW%
SL
http-equiv meta tags for view, rdiff, attach, search* scripts.
%HTTP_EQUIV_ON_EDIT%
SL , UL
http-equiv meta tags for edit script.
%HTTP_EQUIV_ON_PREVIEW%
SL , UL
http-equiv meta tags for preview script.
%DENYWEBCHANGE%
WL
List of users and groups who are not allowed to change topics in the TWiki web. (More in TWikiAccessControl)
%ALLOWWEBCHANGE%
WL
List of users and groups who are allowed to change topics in the TWiki web. (More in TWikiAccessControl)
%DENYTOPICCHANGE%
(any topic)
List of users and groups who are not allowed to change the current topic. (More in TWikiAccessControl)
%ALLOWTOPICCHANGE%
(any topic)
List of users and groups who are allowed to change the current topic. (More in TWikiAccessControl)
%DENYWEBRENAME%
WL
List of users and groups who are not allowed to rename topics in the TWiki web. (More in TWikiAccessControl)
%ALLOWWEBRENAME%
WL
List of users and groups who are allowed to rename topics in the TWiki web. (More in TWikiAccessControl)
%DENYTOPICRENAME%
(any topic)
List of users and groups who are not allowed to rename the current topic. (More in TWikiAccessControl)
%ALLOWTOPICRENAME%
(any topic)
List of users and groups who are allowed to rename the current topic. (More in TWikiAccessControl)
%FINALPREFERENCES%
SL , WL
List of preferences that are not allowed to be overridden by next level preferences
Note: There are some more useful variables defined in the TWikiPreferences like %BR% for line break, colors like %RED% for colored text and small icons like %H% for a Help icon.
Setting Preferences
The syntax for Preferences Variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): [multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [value] Examples:
Set VARIABLENAME = value
Set VARIABLENAME = value
Creating Custom Variables
You can add your own Preference Variables for us across an entire site or a single web, using the standard Preferences syntax. Whatever you include in your Variable will be expanded on display, exactly as if it had been entered directly. You can place formatted text, page links, image paths.
Example: Create a custom logo variable the TWiki web
To place a logo anywhere in a web by typing %MYLOGO%, define the Variable on the web's WebPreferences page, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, ex: LogoTopic:
Set MYLOGO = %PUBURL%/TWiki/LogoTopic/mylogo.gif
-- PeterThoeny - 19 Jan 2003
-- MikeMannix? - 12 May 2002
...discover TWiki details, and how to start your own site.
You can use color coding by web for identification and reference. This table is updated automatically based on WebPreferences settings of the individual webs. Contact caad-yearly@hbt.arch.ethz.ch if you need a separate collaboration web for your team.
(included from SiteMap; change TWikiWebsTable to include from SiteMap instead of TWikiWebsTable)
Template webs were created to act as templates in creating webs. It is now possible to creation webs via the ManagingWebs topic. In the not so distant past TWiki webs were created by hand. The data directory contains the different webs such as Main and TWiki. A web that begins with an underscore "_" character is considered invisible and a template. All files in the _default (or any other web that begins with an underscore) template web will be copied into your new web. The _default web template contains the following topics: WebChanges, WebHome, WebIndex, WebNotify, WebPreferences, WebSearch, WebStatistics and WebTopicList.
Customizing
The web template is useful for administrators to design for creating webs of a certain type. Departmental webs can at least begin with a similar look and feel.
Simply create a web with an underscore for the first character. These can be used by authorized users to create webs from this template.
-- GrantBow - 16 Jan 2003
A text editor, or text processor, handles plain text only, different from a word processor because it doesn't do display formatting like bold type, or mixed font styles, sizes and colors. Advanced text editors are typically used by computer programmers, and have text manipulation features not found or regularly used in word processors, like regular expression search and replace, clip libraries, bookmarks to tag individual lines, upfront display of line numbers, file size and the like, and the ability to save in PC, Mac and Unix formats.
HTML editors are text editors with built-in formatting functions.
Windows Notepad is a simple text editor, designed to be small and fast loading, for taking quick notes.
-- MikeMannix? - 12 May 2002
The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system on one quick reference page.
Create a separator - a horizontal rule - by entering three dashes at the beginning of a blank line: ---. You can enter more than three if you like, for a more visible separator in edit mode: --------------
How do I create a heading?
You can create six sizes of headings - <h1>...<h6> in HTML - by typing, from the beginning of a line, three dashes (-), from one to six plus signs (+), a space, and your heading text. The FAQ questions on this page are created with: ---+++ Have a question?.
You can insert a nested table of contents, generated from headings, by placing %TOC% wherever you like on a page (see TWikiVariables for more %TOC% options).
Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
TWiki interprets text as HTML, and the '<' and '>' characters define where HTML commands start and end. Text inside angle brackets is treated as HTML, and ignored if it doesn't actually do anything - either way, the brackets and its contents are not displayed.
If you want to display angle brackets, enter them as HTML codes instead of typing them in directly:
< = < > = >
You enter:(a > 0)Result:(a > 0)
Some words appear highlighted, with a "?" link at the end. How can I prevent that?
A question mark after a word is a link to a topic that doesn't yet exist - click it to create the new page. This is a TWiki feature - typing a MeaningfulTitle? in a comment is an invitation for someone else to add a new branch to the topic.
To prevent auto-linking - say you want to enter a word like JavaScript (the proper spelling!) - prefix the WikiStyleWord? with the special TWiki HTML tag <nop>:
<nop>WikiStyleWord displays as WikiStyleWord
How can I write fixed font text?
The quickest way is to enclose the text in equal signs:
Text I enter gets wrapped around. How can I keep the formatting as it is?
TWiki interprets text as HTML, so you can use the preformatted HTML option to keep the new line of text as is. Enclose the text in <pre> </pre>, or in TWiki's own <verbatim> </verbatim> tag:
This text will keep its format as it is:
<verbatim>
Unit Price Qty Cost
------- ------ --- ------
aaa 12.00 3 36.00
</verbatim>
The pre tag is standard HTML; verbatim is a special TWiki tag that forces text to fixed font mode, and also prevents other tags and TWiki shortcuts from being expanded.
Yes. The easiest way is to attach a GIF, JPG or PNG file to a topic and then to place it with: %ATTACHURL%/myImage.gif. This works only for the page that the image is attached to.
To place an image on any page, ther are two ways of including inline images.
1. Using URL ending in .gif, .jpg, .jpeg, .png
This is a simple and automatic way of including inline images. Simply write the URL of the image file, this will create the inline image for you. NOTE: The images must be accessible as a URL.
You enter: TWiki http://wiki.arch.ethz.ch/caadtwiki/pub/TWiki/TWikiLogos/twikilogo88x31.gif logo. Result: TWiki logo.
You can upload images directly to your server with FTP access. You can also attach image files to a topic - you could even create a dedicated image topic, like ImageLibrary - and then link to the images directly:
Attach pic.gif to Someweb.SomeTopic
Display with http://wiki.arch.ethz.ch/caadtwiki/pub/Someweb/SomeTopic/pic.gif
2. Using <img> tag
This is a manual process where you have more control over the rendering of the image. Use the <img> tag of HTML to include GIF, JPG and PNG files. Note: The display of the topic is faster if you include the WIDTH and HEIGHT parameters that have the actual image size. http://www.htmlhelp.com/reference/wilbur/special/img.html has more on inline images.
TWikiPreferences defines some commonly used colors: %YELLOW%, %RED%, %PINK%, %PURPLE%, %TEAL%, %NAVY%, %BLUE%, %AQUA%, %LIME%, %GREEN%, %OLIVE%, %MAROON%, %BLACK%, %GRAY%, %SILVER% and %ENDCOLOR%.
You enter:%RED% red text %ENDCOLOR% and %GREEN% green text %ENDCOLOR%Result: red text and green text
Note:%<color>% text must end with %ENDCOLOR% . If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%.
If you need more colors you can use HTML, like <font color="#ff0000"> red text </font>. You can also use the up-to-date style attribute - ex: style="color:#ff0000" - placed in most HTML tags. span is an all-purpose choice: <span style="color:#ff0000">CoLoR</span>. Only old (like 3.x IE & NS) browsers have a problem with style.
The code is the hexadecimal RGB color code, which is simply Red, Green and Blue values in hex notation (base 16, 0-F). For pure red, the RGB components are 255-0-0 - full red (255), no green or blue. That's FF-0-0 in hex, or "#ff000" for Web page purposes. StandardColors lists basic colors.
Working in TWiki is as easy as typing in text - exactly like email. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter WikiWords. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all layed out below - refer back to this page in a pop-up window from the Edit screen.
TWiki Editing Shorthand
Formatting Command:
Example: You write:
You get:
Paragraphs:
Blank lines will create new paragraphs.
1st paragraph
2nd paragraph
1st paragraph
2nd paragraph
Headings:
At least three dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a level 1 heading (most important), two pluses a level 2 heading; the maximum is level 6. Note: A Table of Content can be created automatically with the %TOC% variable, see TWikiVariables. Any heading text after !! is excluded from the TOC; for example, write ---+!! text if you do not want to list a header in the TOC.
---++ Sushi
---+++ Maguro
Sushi
Maguro
Bold Text:
Words get bold by enclosing them in * asterisks.
*Bold*
Bold
Italic Text:
Words get italic by enclosing them in _ underscores.
_Italic_
Italic
Bold Italic:
Words get _bold italic by enclosing them in _ double-underscores.
__Bold italic__
Bold italic
Fixed Font:
Words get shown in fixed font by enclosing them in = equal signs.
=Fixed font=
Fixed font
Bold Fixed Font:
Words get shown in bold fixed font by enclosing them in double equal signs.
==Bold fixed==
Bold fixed
Note: Make sure to "stick" the * _ = == signs to the words, that is, take away spaces.
_This works_,
_this not _
This works,
_this not _
Verbatim Mode:
Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. Note: Use <pre> and </pre> tags instead if you want that HTML code is interpreted. Note: Each tag must be on a line by itself.
Separator:
At least three dashes at the beginning of a line.
-------
List Item:
Three spaces and an asterisk.
* bullet item
bullet item
Nested List Item:
Six, nine, ... spaces and an asterisk.
* nested stuff
nested stuff
Ordered List:
Three spaces and a number.
1 Sushi
1 Dim Sum
Sushi
Dim Sum
Definition List:
Three spaces, the term, a colon, a space, followed by the definition. Note: Terms with spaces are not supported. In case you do have a term with more then one word, separate the words with dashes or with the non-breaking-space entity.
Sushi: Japan
Dim Sum: S.F.
Sushi
Japan
Dim Sum
S.F.
Table:
Optional spaces followed by the cells enclosed in vertical bars. Note:| *bold* | cells are rendered as table headers. Note:| spaced | cells are rendered center aligned. Note:| spaced | cells are rendered right aligned. Note:| 2 colspan || cells are rendered as multi-span columns. Note: In case you have a long row and you want it to be more readable when you edit the table you can split the row into lines that end with a '\' backslash character.
WikiWord Links:
CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically. Note: In case you want to link to a topic in a different TWiki web write Webname.TopicName.
Forced Links:
You can create a forced internal link by enclosing words in double square brackets.
Note: Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[text formatting FAQ]] links to topic TextFormattingFAQ. You can also refer to a different web and use anchors.
Specific Links:
Create a link where you can specify the link text and the link reference separately, using nested square brackets like [[reference][text]]. Internal link references (e.g. WikiSyntax) and external link references (e.g. http://TWiki.org/) are supported.
Note: The same Forced Links rules apply for internal link references.
Note: For external link references, you can simply use a space instead of ][ to separate the link URL from the descriptive text.
Note: Anchor names can be added as well, like [[WebHome#MyAnchor][go home]] and [[http://gnu.org/#Action][GNU Action]].
Anchors:
You can define a link reference inside a TWiki topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
[[WebHome#NotThere]]
[[#MyAnchor][Jump]]
#MyAnchor To here
Prevent a Link:
Prevent a WikiWord from being linked by prepending it with the <nop> tag.
<nop>SunOS
SunOS
Disable Links:
You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.
Note: Each tag must be on a line by itself.
Note: This also works for TWiki tables, but only if you add a blank line between the end of the table and the closing </noautolink> tag (known issue of the TablePlugin).
<noautolink>
RedHat &
SuSE
</noautolink>
RedHat &
SuSE
Mailto: Links:
To create 'mailto:' links that have more descriptive link text, specify subject lines or message bodies, or omit the email address, you can write [[mailto:user@domain descriptive text]].
You can use just about any HTML tag without a problem - however, there are a few usability and technical considerations to keep in mind.
HTML and TWiki Usability
On collaboration pages, it's preferable NOT to use HTML, and to use TWiki shorthand instead - this keeps the text uncluttered and easy to edit.
NOTE: TWiki is designed to work with a wide range of browsers and computer platforms, holding to HTML 3.2 compatibility in the standard installation - adding raw HTML, particularly browser-specific tags (or any other mark-up that doesn't degrade well) will reduce compatibility.
TWiki HTML Rendering
TWiki converts shorthand notation to XHTML 1.0 for display. To copy a fully marked-up page, simply view source in your browser and save the contents.
If you need to save HTML frequently, you may want to check out TWiki:Plugins/GenHTMLAddon - it will "generate a directory containing rendered versions of a set of TWiki pages together with any attached files."
NOTE: The opening and closing angle brackets - <...> - of an HTML tag must be on the same line, or the tag will be broken.
This feature allows you to enter an unclosed angle bracket - as a greater than or less than symbol - and have it automatically rendered as if you had entered its HTML character, <, ex: a > b
If you're pasting in preformatted HTML text and notice problems, check the file in a text processor with no text wrap. Also, save without hard line breaks on text wrap, in your HTML editing program.
Hyperlinks
Being able to create links without any formatting required is a core TWiki feature, made possible with WikiWords. New TWiki linking rules are a simple extension of the syntax that provide a new set of flexible options.
Internal Links
GoodStyle is a WikiWord that links to the GoodStyle topic located in the current TWiki web.
NotExistingYet? is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)
External Links
http://..., https://..., ftp://..., gopher://..., news://..., file://..., telnet://...
and mailto:...@... are linked automatically.
Email addresses like name@domain.com are linked automatically.
You can also write [[http://yahoo.com Yahoo home page]] as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.
TWiki Variables
Variables are names that are enclosed in percent signs % that are expanded on the fly.
%TOC% : Automatically generates a table of contents based on headings in a topic - see the top of this page for an example.
%WEB% : The current web, is TWiki.
%TOPIC% : The current topic name, is TextFormattingRules.
%ATTACHURL% : The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as %ATTACHURL%/image.gif to show the URL of the file or the image in your text.
%INCLUDE{"SomeTopic"}% : Server side include, includes another topic. The current TWiki web is the default web. Example: %INCLUDE{"TWiki.SiteMap"}%
%SEARCH{"sushi"}% : Inline search showing the search result embedded in a topic. FormattedSearch gives you control over formatting, used to create web-based applications.
Plugins provide additional text formatting capabilities and can extend the functionality of TWiki into many other areas. For example, the optional SpreadSheetPlugin lets you create a spreadsheet with the same basic notation used in TWiki tables.
Available Plugins are located in the Plugins web on TWiki.org. Currently enabled plugins on this TWiki installation, as listed by %PLUGINDESCRIPTIONS%:
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
Check on current Plugin status and settings for this site in TWikiPreferences.
Common Editing Errors
TWiki formatting rules are fairly simple to use and quick to type. However, there are some things to watch out for, taken from the TextFormattingFAQ:
Q: Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
A: The '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<' instead of '<', and '>' instead of '>'. Example: Type 'prog <filename>' to get 'prog <filename>'.
Q: Why is the '&' character sometimes not displayed?
Topics get locked for some time (default is one hour) whenever a user edits, previews or saves a topic. This is to prevent simultaneous topic updates. There is a lock warning if another user tries to edit a topic while the lock is still on.
It is worth noting that all topic changes you do within the lock time will go into the same revision. In other words, if you find a mistake immediately after saving the topic, then TWiki will pretend that it never happened if you fix it while the topic is still locked.
You can remove the lock by checking the "Release edit lock" checkbox in preview. This is a way to let other people know that you are done with your editing. Note: Please remember not to go back in your browser in case you checked the box and after that you decide to do more changes to the topic. Instead press the Edit link to re-edit your page.
Note: The initial state of the checkbox can be set to on with the RELEASEEDITLOCKCHECKBOX preferences variable. See TWikiPreferences for more.
Since wabi-sabi represents a comprehensive Japanese world view or aesthetic system, it is difficult to explain precisely in western terms. According to Leonard Koren, wabi-sabi is the most conspicuous and characteristic feature of what we think of as traditional Japanese beauty and it "occupies roughly the same position in the Japanese pantheon of aesthetic values as do the Greek ideals of beauty and perfection in the West."
Wabi-sabi is a beauty of things imperfect, impermanent, and incomplete. It is the beauty of things modest and humble. It is the beauty of things unconventional.
The concepts of wabi-sabi correlate with the concepts of Zen Buddhism, as the first Japanese involved with wabi-sabi were tea masters, priests, and monks who practiced Zen. Zen Buddhism originated in India, traveled to China in the 6th century, and was first introduced in Japan around the 12th century. Zen emphasizes "direct, intuitive insight into transcendental truth beyond all intellectual conception." At the core of wabi- sabi is the importance of transcending ways of looking and thinking about things/existence.
Statistics for TWiki Web Month: Topic views: Topic saves: File uploads: Most popular topic views: Top contributors for topic save and uploads: May 2009 1350 0 0 113 ...
RED THIS IS NOT THE PLACE FOR STUDENTS TO REGISTER ENDCOLOR RED Even not for those, who cannot find another place. ENDCOLOR RED To make it clear. If you are not sure ...
TWiki Site-Level Preferences The following are site-level settings that affect all users in all webs on this TWikiSite. They can be selectively overwritten on the ...
Welcome, WIKIUSERNAME ! RED This is the standard TWiki welcome and not related to CAAD Chair ENDCOLOR Welcome to TWiki! This is a TWikiSite (pronounced twee-kee site ...
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute includes h then the attachment is ...
TWiki Web Preferences The following settings are web preferences of the TWiki web. These preferences overwrite the site-level preferences in TWIKIWEB . WIKIPREFSTOPIC ...
Edit Table Plugin This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an Edit table button if preceeded by an EDITTABLE ...
To edit pages on this TWiki Collaborative Web, you must have a registered user name in WikiNotation. To register as a new user, simply fill out this form: First last ...
TOC STARTINCLUDE # TWiki User Authentication TWiki site access control and user activity tracking options TWiki does not authenticate users internally, it depends ...
## TWiki Username vs. Login Username This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet . TWiki internally ...
Welcome to TWiki: a flexible, powerful, secure, yet simple web-based collaboration platform. Use TWiki to run a project development space, a document management system ...
Main Features of TWiki Any web browser: Edit existing pages or create new pages by using any web browser. There is no need to upload pages. Edit link: To edit a page ...
TOC STARTINCLUDE # TWiki Access Control Restricting read and write access to topics and webs, by Users and groups TWikiAccessControl allows you restrict access to ...
TWiki Admin Cook Book This page has many tips and tricks, particularly useful when you're installing TWiki for the first time. This guide is most useful RED before ...
TOC STARTINCLUDE # TWiki Installation Guide Installation instructions for the TWiki 01-Feb-2003 production release. Update notes for the new RCS configuration are ...
TOC STARTINCLUDE # 20-Minute TWiki This step-by-step, hands-on tutorial gets you up to speed with all the TWikiSite basics, in mere minutes ... 1. Get set... Open ...
TOC STARTINCLUDE # TWiki Upgrade Guide Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003 Overview This guide describes how to upgrade ...
## TWiki Upgrade Notes for Version 01 May 2000 If you are coming from a version earlier than the 01 May 2000 production release, please see TWikiUpgradeTo01May2000 ...
To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things: Back up your system. Update the templates in the ...
TOC STARTINCLUDE # TWiki Upgrade Guide Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release) This guide describes ...
TOC STARTINCLUDE #FileSystem # Appendix A: TWiki Filesystem Annotated directory and file listings, for the 01-Feb-2003 TWiki production release. Who and What is This ...
TOC STARTINCLUDE # Windows Install Cookbook Introduction This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as ...
TOC STARTINCLUDE # TWiki System Requirements Server and client requirements for TWiki 01-Feb-2003 Low client and server requirements are core features that keep TWiki ...
TOC STARTINCLUDE # TWiki::Func Module Documentation Official list of stable TWiki functions for Plugin developers Description This module defines official funtions ...
TOC{depth "4"} STARTINCLUDE # TWiki Text Formatting Working in TWiki is as easy as typing in text exactly like email . You don't need to know HTML, though you can ...
TOC STARTINCLUDE # TWiki Templates Definition of the templates used to render all HTML pages displayed in TWiki Overview The new modular template system offers flexible ...
Include Topics and Web Pages Using INCLUDE{...} Variable Use the INCLUDE{...} variable to embed the content of another topic or web page inside a TWiki topic. The ...
TWiki Topics TOC The basic building block of a TWiki site is called a topic , identified by a unique, hopefully descriptive, TWIKIWEB .WikiWord title. It may seem ...
Welcome to TWiki. This page assumes that you are a new user to TWiki, and that you've never heard of Wiki before. Here are the most important pages you should know ...
# TWiki Shorthand Basics If you can enter text, you're ready for TWiki. With a few simple, intuitive TextFormattingRules, you'll be able to use plain text to create ...
Instant TWiki Site Enhancements These quick enhancements are aimed at improving TWiki's ease-of-use. New TWiki site administrators are especially encouraged to review ...
TWiki Reference Manual ( WIKIVERSION ) This page contains all documentation topics as one long, complete reference sheet. BR Doubleclick anywhere to return to the ...
Administrator Skills Assumptions For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from ...
Text Editor A text editor, or text processor, handles plain text only, different from a word processor because it doesn't do display formatting like bold type, or ...
TWiki's TWiki web SCRIPTURL /view SCRIPTSUFFIX /TWiki The Documentation Web of TWiki. TWiki is a Web-Based Collaboration Platform for the Corporate World. INCLUDE ...
RSS Feed This is the base for the RSS feed for each web. Each web has a WebRss that should contain the following text: TWiki's INCLUDINGWEB web SCRIPTURL /view SCRIPTSUFFIX ...
TOC STARTINCLUDE # TWiki Site Tools Utilities for searching, navigation, and monitoring site activity TWikiSiteTools include utilities for navigating, searching and ...
The box at the top of each page. Enter a topic name to quickly jump to the topic, for example: WebNotify to jump to WebNotify in the current web MAINWEB .WebNotify ...
TOC STARTINCLUDE # TWiki Plugins Plug-in enhanced feature add-ons, with a Plugin API for developers Overview You can add Plugins to extend TWiki's functionality, ...
TOC STARTINCLUDE # TWiki Glossary Simple glossary of TWiki terms Term Definition Attachment: Any type of file that is uploaded via browser and attached to a topic ...
TOC STARTINCLUDE # TWiki Variables Special text strings expand on the fly to display user data or system info TWikiVariables are text strings VARIABLE that expand ...
Interwiki Plugin The InterwikiPlugin links ExternalSite:Page text to external sites based on aliases defined in the TWIKIWEB .InterWikis topic. This plugin is inspired ...
This is a subscription service to be automatically notified by e-mail when topics change in this TWiki web. This is a convenient service, so you do not have to come ...
TOC STARTINCLUDE # TWiki Forms Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web topic Overview ...
TWiki Documentation Graphics This is one way to create a library of common icons, accessible through user-defined TWikiVariables set in WebPreferences, or in TWikiPreferences ...
Welcome to TWiki: a flexible, powerful, secure, yet simple web-based collaboration platform. Use TWiki to run a project development space, a document management system, a knowledge base or any other groupware tool on either on an intranet or on the Internet.
This is the place to learn about TWiki features, find where to download it, and try it out for yourself...
DefaultPlugin: This plugin can be used to specify some simple custom rendering rules. It also renders deprecated *_text_* as bold italic text.
EditTablePlugin: Edit TWiki tables using edit fields, date pickers and drop down boxes
InterwikiPlugin: Link ExternalSite:Page text to external sites based on aliases defined in the InterWikis topic.
ADMINS: In less than an hour, you can read through and customize the User's Guide to reflect the exact feature set enabled on your own TWiki site. See also other enhancement pages:
InstantEnhancements: Simple tips (using just browser, no install needed) and quick (max couple of minutes).
TWiki Reference Manual
Documentation for webmasters, system administrators, project managers, team leaders, and all other users of the TWiki advanced online collaboration platform.
...discover TWiki details, and how to start your own site.
You can use color coding by web for identification and reference. This table is updated automatically based on WebPreferences settings of the individual webs. Contact caad-yearly@hbt.arch.ethz.ch if you need a separate collaboration web for your team.
Administrator Skills Assumptions For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from ...
TOC STARTINCLUDE #FileSystem # Appendix A: TWiki Filesystem Annotated directory and file listings, for the 01-Feb-2003 TWiki production release. Who and What is This ...
BookView is an option available from the WebSearch topic. It allows you to display the result in "book view", that is, the whole content of topics is shown instead ...
Change password Forgot your old password? Then use ResetPassword instead. Please only use ResetPassword in case you really forgot your password. Thank you. Your TWIKIWEB ...
Default TWiki Plugin The default plugin is used for some deprecated rendering of older TWiki versions and of JosWiki. This plugin can also be used to specify some ...
FAQ: How do I delete or rename a topic? Answer: New to the 01-Sep-2001 version of TWiki, you can rename, move and delete topics directly from your browser (previously ...
Use the "Minor changes, don't notify" checkbox in preview in case you only make a minor change to a topic and you do not want to inform everybody who is on the WebNotify ...
FAQ: Why does the topic revision not increase when I edit a topic? Answer: The same topic revision will be used when you save a topic again within a certain time ...
Edit Table Plugin This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an Edit table button if preceeded by an EDITTABLE ...
Empty TWiki Plugin This is an empty plugin you can use as a template to build your own TWIKIWEB .TWikiPlugins. This plugin does nothing, but is ready to be used. ...
TOC STARTINCLUDE # File Attachments Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from ...
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute includes h then the attachment is ...
FAQ: TWiki has a GPL (GNU General Public License). What is GPL? Answer: TWiki is distributed under the GNU General Public License, see TWikiDownload. GPL is one of ...
The box at the top of each page. Enter a topic name to quickly jump to the topic, for example: WebNotify to jump to WebNotify in the current web MAINWEB .WebNotify ...
GoodStyle Collaboration Tips TWiki has a very simple text formatting shorthand . In any case, you won't go wrong if you simply: start each line without spaces separate ...
Hide/Unhide Attachments You can hide/unhide file attachments. In the FileAttachment table, click on an action link, enable the Hide file checkbox, then click Change ...
Include Topics and Web Pages Using INCLUDE{...} Variable Use the INCLUDE{...} variable to embed the content of another topic or web page inside a TWiki topic. The ...
Install an Encrypted Password This form can be used only by the MAINWEB .TWikiAdminGroup users to install an encrypted password generated by a user with ResetPassword ...
Installed Plugins Plugins are mainly user-contributed add-ons that enhance and extend TWiki features and capabilities. A limited number of plugins are included in ...
Instant TWiki Site Enhancements These quick enhancements are aimed at improving TWiki's ease-of-use. New TWiki site administrators are especially encouraged to review ...
Inter-Wiki Link Rules (or Links to other Sites) This topic lists all aliases needed to map Inter-Site links to external wikis/sites. Whenever you write ExternalSite ...
Interwiki Plugin The InterwikiPlugin links ExternalSite:Page text to external sites based on aliases defined in the TWIKIWEB .InterWikis topic. This plugin is inspired ...
Main Features of TWiki Any web browser: Edit existing pages or create new pages by using any web browser. There is no need to upload pages. Edit link: To edit a page ...
TOC STARTINCLUDE # Managing Topics Browser-based rename, move, and delete for individual topics Overview You can use browser-based controls to change a topic's name ...
TOC STARTINCLUDE # Managing Webs Adding webs is a web based operation; renaming and deleting webs are manual operations done directly on the server Overview A TWikiSite ...
STARTINCLUDE ## Meta Data Rendering Various meta data can be stored in topics MetaDataDefinition This is rendered using the META variable. This is mostly used in ...
SPLIT KEY : VALUE SPLIT Personal Preferences (details in TWIKIWEB .TWikiVariables) Horizontal size of text edit box: Set EDITBOXWIDTH 70 Vertical size of text edit ...
Peter Thoeny is the author of TWiki and therefore a TWiki:Codev/CoreTeam member and a TWikiContributor. See home page at TWiki:Main/PeterThoeny and MAINWEB .PeterThoeny ...
Background Image for Preview Preview looks like the real page, but the links leed to an oops dialog warning users of not yet saved topics. In addition, a background ...
Regular Expressions TOC Introduction Regular expressions (REs), unlike simple queries, allow you to search for text which matches a particular pattern. REs are similar ...
Request for reset of password Please only use this ResetPassword form in case you really forgot your password. Otherwise just change it using ChangePassword. Thank ...
FAQ: I've problems with the WebSearch. There is no Search Result on any inquiry. By clicking the Index topic it's the same problem. Answer: That is an indication ...
FAQ: What happens if two of us try to edit the same topic simultaneously? Answer: The second person gets a warning that the topic is currently being edited by another ...
TWiki Site Map STARTINCLUDE TWiki Site Map Use to... SEARCH{ "\ Set SITEMAPLIST \ on" regex "on" web " MAINWEB , TWIKIWEB , all" nototal "on" nosearch "on" format ...
TOC STARTINCLUDE ## Site Usage Statistics You can automatically generate usage statistics for all webs. To enable this: Make sure variable $doLogTopicView, $doLogTopicSave ...
The 256 Standard Colors This table can be used to choose a color in WEBPREFSTOPIC of each web. #000000 #000033 #000066 #000099 #0000CC #0000FF #003300 #003333 #003366 ...
Welcome to TWiki. This page assumes that you are a new user to TWiki, and that you've never heard of Wiki before. Here are the most important pages you should know ...
TOC STARTINCLUDE # TWiki Access Control Restricting read and write access to topics and webs, by Users and groups TWikiAccessControl allows you restrict access to ...
TWiki Admin Cook Book This page has many tips and tricks, particularly useful when you're installing TWiki for the first time. This guide is most useful RED before ...
TWiki Contributor A TWiki contributor is a person devoting his/her time to contribute on the development of the Open Source project TWiki, hosted at http://TWiki ...
TWiki Documentation Graphics This is one way to create a library of common icons, accessible through user-defined TWikiVariables set in WebPreferences, or in TWikiPreferences ...
TWiki Reference Manual ( WIKIVERSION ) This page contains all documentation topics as one long, complete reference sheet. BR Doubleclick anywhere to return to the ...
FAQ: I would like to install TWiki on my server. Can I get the source? Answer: TWiki is distributed under the GnuGeneralPublicLicense. You can request the source ...
Please bring your enhancement requests to TWiki:Codev.FeatureEnhancementRequest Related Topics TWikiHistory has a list of added features in TWiki. TWikiPlannedFeatures ...
Frequently Asked Questions About TWiki This is a real FAQ, and also a demo of one easily implemented knowledge base solution. See how it's done, click Edit . SEARCH ...
TOC STARTINCLUDE # TWiki Forms Form-based input in topics, with name/value pairs stored as Meta Data variables; choose one of multiple forms per web topic Overview ...
TOC STARTINCLUDE # TWiki::Func Module Documentation Official list of stable TWiki functions for Plugin developers Description This module defines official funtions ...
TOC STARTINCLUDE # TWiki Glossary Simple glossary of TWiki terms Term Definition Attachment: Any type of file that is uploaded via browser and attached to a topic ...
TOC STARTINCLUDE # TWiki Installation Guide Installation instructions for the TWiki 01-Feb-2003 production release. Update notes for the new RCS configuration are ...
TOC STARTINCLUDE #MetaDataDefinition # TWiki Meta Data Additional topic data, program-generated or from TWikiForms, is stored in META variable name/value pairs Overview ...
Features requested, planned or under construction are listed at the TWiki development home TWiki:Codev.WebHome Related Topics TWikiHistory has a list of added features ...
TOC STARTINCLUDE # TWiki Plugins Plug-in enhanced feature add-ons, with a Plugin API for developers Overview You can add Plugins to extend TWiki's functionality, ...
TWiki Site-Level Preferences The following are site-level settings that affect all users in all webs on this TWikiSite. They can be selectively overwritten on the ...
To edit pages on this TWiki Collaborative Web, you must have a registered user name in WikiNotation. To register as a new user, simply fill out this form: First last ...
TWiki is a Web-based collaboration platform A TWiki site is an easy-to-use, full-featured open communications environment: people anywhere on the Web or on an intranet ...
TOC STARTINCLUDE # TWiki Site Tools Utilities for searching, navigation, and monitoring site activity TWikiSiteTools include utilities for navigating, searching and ...
TOC STARTINCLUDE # TWiki Skins Skins overlay regular templates with alternate header/footer layouts; topic text is not affected Overview Skins are customized TWikiTemplates ...
TOC STARTINCLUDE # TWiki System Requirements Server and client requirements for TWiki 01-Feb-2003 Low client and server requirements are core features that keep TWiki ...
TOC STARTINCLUDE # TWiki Templates Definition of the templates used to render all HTML pages displayed in TWiki Overview The new modular template system offers flexible ...
TWiki Topics TOC The basic building block of a TWiki site is called a topic , identified by a unique, hopefully descriptive, TWIKIWEB .WikiWord title. It may seem ...
TOC STARTINCLUDE # 20-Minute TWiki This step-by-step, hands-on tutorial gets you up to speed with all the TWikiSite basics, in mere minutes ... 1. Get set... Open ...
TOC STARTINCLUDE # TWiki Upgrade Guide Upgrade from the previous TWiki 01-Dec-2001 production release to TWiki 01-Feb-2003 Overview This guide describes how to upgrade ...
## TWiki Upgrade Notes for Version 01 May 2000 If you are coming from a version earlier than the 01 May 2000 production release, please see TWikiUpgradeTo01May2000 ...
TOC STARTINCLUDE # TWiki Upgrade Guide Upgrade from TWiki 01-Dec-2000 or TWiki 01-Sep-2001 to TWiki 01-Dec-2001 (previous to new full release) This guide describes ...
To upgrade an earlier TWiki version like 01 Sep 1999 to version 01 May 2000 you should do the following things: Back up your system. Update the templates in the /templates ...
TOC STARTINCLUDE # TWiki User Authentication TWiki site access control and user activity tracking options TWiki does not authenticate users internally, it depends ...
## TWiki Username vs. Login Username This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet . TWiki internally ...
TOC STARTINCLUDE # TWiki Variables Special text strings expand on the fly to display user data or system info TWikiVariables are text strings VARIABLE that expand ...
INCLUDE{" TWIKIWEB .SiteMap"} (included from TWIKIWEB .SiteMap; change INCLUDINGWEB . INCLUDINGTOPIC to include from SiteMap instead of TWikiWebsTable)
TOC Template Web Purpose Template webs were created to act as templates in creating webs. It is now possible to creation webs via the TWIKIWEB .ManagingWebs topic ...
Text Editor A text editor, or text processor, handles plain text only, different from a word processor because it doesn't do display formatting like bold type, or ...
Text Formatting FAQ The most frequently asked questions about text formatting are answered. Also, TextFormattingRules contains the complete TWiki shorthand system ...
TOC{depth "4"} STARTINCLUDE # TWiki Text Formatting Working in TWiki is as easy as typing in text exactly like email . You don't need to know HTML, though you can ...
Tim Berners-Lee invented the World Wide Web while working at CERN in 1989. See his biography at http://www.w3.org/People/Berners-Lee/ Main.PeterThoeny 12 Jan 2003 ...
GREEN students of CAAD 1 ws05/06 register here ENDCOLOR RED read the small print below ENDCOLOR First last name: 'a') (ch 'A') (ch Email address: Team name: 'a') ...
Topics get locked for some time (default is one hour) whenever a user edits, previews or saves a topic. This is to prevent simultaneous topic updates. There is a lock ...
Since wabi-sabi represents a comprehensive Japanese world view or aesthetic system, it is difficult to explain precisely in western terms. According to Leonard Koren ...
SEARCH{". " web " INCLUDINGWEB " regex "on" nosearch "on" order "modified" reverse "on" limit "50"} See 100, 200, 400, 800 most recent changes See all changes
INCLUDE{"DocsUserNote"} Web Changes Notification Service Each TWiki web has an automatic email notification service that sends you an email with links to all of the ...
Welcome to TWiki: a flexible, powerful, secure, yet simple web-based collaboration platform. Use TWiki to run a project development space, a document management system ...
This is a subscription service to be automatically notified by e-mail when topics change in this TWiki web. This is a convenient service, so you do not have to come ...
TWiki Web Preferences The following settings are web preferences of the TWiki web. These preferences overwrite the site-level preferences in TWIKIWEB . WIKIPREFSTOPIC ...
TWiki's TWiki web SCRIPTURL /view SCRIPTSUFFIX /TWiki The Documentation Web of TWiki. TWiki is a Web-Based Collaboration Platform for the Corporate World. INCLUDE ...
RSS Feed This is the base for the RSS feed for each web. Each web has a WebRss that should contain the following text: TWiki's INCLUDINGWEB web SCRIPTURL /view SCRIPTSUFFIX ...
Simple search: Topic text (body) All webs (not only INCLUDINGWEB web) Topic name TWIKIWEB .BookView Advanced search: Topic text (body) Search all public INCLUDINGWEB ...
Web Site Tools STARTINCLUDE (More options in WebSearch) WebChanges: Display recent changes to the INCLUDINGWEB web WebIndex: List all INCLUDINGWEB topics in alphabetical ...
Statistics for TWiki Web Month: Topic views: Topic saves: File uploads: Most popular topic views: Top contributors for topic save and uploads: May 2009 1350 0 0 113 ...
NOTE: This Wiki topic does not exist WARNING: This topic name is not recommended because it will not be linked automatically. See TWIKIWEB .WikiWord for details. ...
NOTE: This Wiki topic does not exist yet If you would like to create this page: Simply click on the Create link at the bottom of this page. If you intend to do a ...
Welcome, WIKIUSERNAME ! RED This is the standard TWiki welcome and not related to CAAD Chair ENDCOLOR Welcome to TWiki! This is a TWikiSite (pronounced twee-kee site ...
FAQ: So what is this WikiWiki thing exactly? Answer: A set of pages of information that are open and free for anyone to edit as they wish. They are stored in a server ...
FAQ: Everybody can edit any page, this is scary. Doesn't that lead to chaos? Answer: TWiki is one of many WikiWikiClones, the first one was built by Ward Cunningham ...
Your name, usually your first and last name connected without a space. For example, Tim Berners-Lee's WikiName is TimBernersLee. X Your name is also a potentially ...
References on Wiki and Collaboration Some useful articles and books around collaboration and the Wiki technology in particular. Wiki Technology and TWiki Book: The ...
# TWiki Shorthand Basics If you can enter text, you're ready for TWiki. With a few simple, intuitive TextFormattingRules, you'll be able to use plain text to create ...
A WikiTopic is one unit of information in a T/Wiki web. It is more or less a universal term in the world of Wikis. Each WikiTopic is displayed as one Web page in your ...
TWiki is a Wiki Wiki clone and has its root in JOS Wiki. TWiki's home is at http://TWiki.org/ TWiki takes a lot of ideas from Ward Cunningham's remarkable Wiki Wiki ...
A WikiWord consists of two or more words with initial capitals, run together. When you type a WikiWord, you establish a hyperlink. It's as easy as that. WikiWords ...
TOC STARTINCLUDE # Windows Install Cookbook Introduction This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as ...
STARTINCLUDE You are currently in the INCLUDINGWEB web. The color code for this web is this background, so you know where you are. If you are not familiar with the ...
Number of topics: 142
See also the faster WebTopicList
This is a subscription service to be automatically notified by e-mail when topics change in this TWiki web. This is a convenient service, so you do not have to come back and check all the time if something has changed. To subscribe, please add a bullet with your WikiName in alphabetical order to this list:
Format: <space><space><space>, followed by: * Main.yourWikiName (if you want that the e-mail address in your home page is used) * Main.yourWikiName - yourEmailAddress (if you want to specify a different e-mail address) * Main.anyTWikiGroup (if you want to notify all members of a particular TWikiGroup)
Related topics:TWikiUsers, TWikiRegistration
The following settings are web preferences of the TWiki web. These preferences overwrite the site-level preferences in TWikiPreferences, and can be overwritten by user preferences (your personal topic, eg: TWikiGuest in the Main web).
Preferences:
If yes, Set SITEMAPLIST = on, and add the "what" and "use to..." description for the site map. Make sure to list only links that include the name of the web, e.g. TWiki.Topic links.
Set SITEMAPUSETO = ...discover TWiki details, and how to start your own site.
Exclude web from a web="all" search: (Set to on for hidden webs)
Set NOSEARCHALL = on
Prevent automatic linking of WikiWords and acronyms (if set to on); link WikiWords (if empty); can be overwritten by web preferences:
Set NOAUTOLINK =
Note: Use the [[...][...]] syntax to link topics in case you disabled WikiWord linking. The <noautolink> ... </noautolink> syntax can be used to prevents links within a block of text.
Default template for new topics and form(s) for this web:
Users or groups allowed to change or rename this WebPreferences topic: (I.e. TWikiAdminGroup)
Set ALLOWTOPICCHANGE =
Set ALLOWTOPICRENAME =
Web preferences that are not allowed to be overridden by user preferences:
Set FINALPREFERENCES = WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, DENYWEBRENAME, ALLOWWEBRENAME
Notes:
A preference is defined as: 6 spaces * Set NAME = value Example:
Set WEBBGCOLOR = #FFFFC0
Preferences are used as TWikiVariables by enclosing the name in percent signs. Example:
When you write variable %WEBBGCOLOR% , it gets expanded to #FFE0B0 .
The sequential order of the preference settings is significant. Define preferences that use other preferences first, i.e. set WEBCOPYRIGHT before WIKIWEBMASTER since %WEBCOPYRIGHT% uses the %WIKIWEBMASTER% variable.
You can introduce new preferences variables and use them in your topics and templates. There is no need to change the TWiki engine (Perl scripts).
TWiki's TWiki web
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki
The Documentation Web of TWiki. TWiki is a Web-Based Collaboration Platform for the Corporate World.en-usCopyright 2009, Peter Thoeny and contributing authors.Peter Thoeny [Peter@Thoeny.com]Peter Thoeny [Peter@Thoeny.com]TWikiTWiki.TWikiTWiki.TWiki
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki
http://wiki.arch.ethz.ch/caadtwiki/pub/TWiki/TWikiLogos/twikilogo88x31.gifWebStatistics
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/WebStatistics
Statistics for TWiki Web Month: Topic views: Topic saves: File uploads: Most popular topic views: Top contributors for topic save and uploads: May 2009 1350 0 0 113 ...2009-05-08T00:56Zguest1.1390updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WebStatisticshttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WebStatisticsTwikiCaad3MemberRegistration
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TwikiCaad3MemberRegistration
GREEN students of CAAD 1 ws05/06 register here ENDCOLOR RED read the small print below ENDCOLOR First last name: 'a') (ch 'A') (ch Email address: Team name: 'a') ...2005-10-30T16:48ZPiaFricker1.10updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TwikiCaad3MemberRegistrationhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TwikiCaad3MemberRegistrationTWikiRegistration
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiRegistration
No permission to read topic TWiki.TWikiRegistration perhaps you need to log in? 2005-10-30T12:28ZPiaFricker1.19updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiRegistrationhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiRegistrationTWikiPreferences
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiPreferences
TWiki Site-Level Preferences The following are site-level settings that affect all users in all webs on this TWikiSite. They can be selectively overwritten on the ...2005-10-06T09:03ZPiaFricker1.56updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiPreferenceshttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiPreferencesWelcomeGuest
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/WelcomeGuest
Welcome, WIKIUSERNAME ! RED This is the standard TWiki welcome and not related to CAAD Chair ENDCOLOR Welcome to TWiki! This is a TWikiSite (pronounced twee-kee site ...2004-10-26T21:46ZKarstenDroste1.22updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WelcomeGuesthttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WelcomeGuestFileAttribute
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/FileAttribute
Each FileAttachment in a Topic has an attribute string. At present only only the hidden attribute is supported. If the attribute includes h then the attachment is ...2004-10-08T12:52ZSusanneSchumacher1.3updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/FileAttributehttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/FileAttributeWebPreferences
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/WebPreferences
TWiki Web Preferences The following settings are web preferences of the TWiki web. These preferences overwrite the site-level preferences in TWIKIWEB . WIKIPREFSTOPIC ...2004-10-08T08:32ZKarstenDroste1.20updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WebPreferenceshttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WebPreferencesEditTablePlugin
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/EditTablePlugin
Edit Table Plugin This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an Edit table button if preceeded by an EDITTABLE ...2004-09-17T01:40ZPeterThoeny1.24updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/EditTablePluginhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/EditTablePluginCaadLogos
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/CaadLogos
Main.KarstenDroste 01 Sep 2004 version with extra space left and right: default logo for this twiki: 2004-09-02T09:13ZOliverFritz1.2updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/CaadLogoshttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/CaadLogosTWikiRegistrationOLD
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiRegistrationOLD
To edit pages on this TWiki Collaborative Web, you must have a registered user name in WikiNotation. To register as a new user, simply fill out this form: First last ...2004-09-01T07:51ZKarstenDroste1.9updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiRegistrationOLDhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiRegistrationOLDTWikiUserAuthentication
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiUserAuthentication
TOC STARTINCLUDE # TWiki User Authentication TWiki site access control and user activity tracking options TWiki does not authenticate users internally, it depends ...2004-09-01T07:50ZKarstenDroste1.16updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiUserAuthenticationhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiUserAuthenticationTWikiUsernameVsLoginUsername
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiUsernameVsLoginUsername
## TWiki Username vs. Login Username This section applies only if your TWiki is installed on a server that is both authenticated and on an intranet . TWiki internally ...2004-09-01T07:50ZKarstenDroste1.8updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiUsernameVsLoginUsernamehttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiUsernameVsLoginUsernameWebHome
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/WebHome
Welcome to TWiki: a flexible, powerful, secure, yet simple web-based collaboration platform. Use TWiki to run a project development space, a document management system ...2004-09-01T07:50ZKarstenDroste1.79updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WebHomehttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/WebHomeMainFeatures
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/MainFeatures
Main Features of TWiki Any web browser: Edit existing pages or create new pages by using any web browser. There is no need to upload pages. Edit link: To edit a page ...2004-09-01T07:50ZKarstenDroste1.2updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/MainFeatureshttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/MainFeaturesTWikiAccessControl
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiAccessControl
TOC STARTINCLUDE # TWiki Access Control Restricting read and write access to topics and webs, by Users and groups TWikiAccessControl allows you restrict access to ...2004-09-01T07:50ZKarstenDroste1.28updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiAccessControlhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiAccessControlTWikiAdminCookBook
http://wiki.arch.ethz.ch/caadtwiki/bin/view/TWiki/TWikiAdminCookBook
TWiki Admin Cook Book This page has many tips and tricks, particularly useful when you're installing TWiki for the first time. This guide is most useful RED before ...2004-09-01T07:50ZKarstenDroste1.3updatedmajorhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiAdminCookBookhttp://wiki.arch.ethz.ch/caadtwiki/bin/rdiff/TWiki/TWikiAdminCookBook
This is the base for the RSS feed for each web.
Each web has a WebRss that should contain the following text:
<channel rdf:about="%SCRIPTURL%/view%SCRIPTSUFFIX%/%INCLUDINGWEB%">
<title>%WIKITOOLNAME%'s %INCLUDINGWEB% web</title>
<link>%SCRIPTURL%/view%SCRIPTSUFFIX%/%INCLUDINGWEB%</link>
<description>(the description of the web). TWiki is a Web-Based Collaboration Platform for the Corporate World.</description>
%INCLUDE{"%TWIKIWEB%.WebRssBase"}%
The list above provides the TWikiSiteTools used to navigate, search and maintain a particular web. It is included within other topics using the following directive:
%INCLUDE{"%TWIKIWEB%.WebSiteTools"}%
List all topics which include this WebSiteTools topic.
This is the standard TWiki welcome and not related to CAAD Chair
Welcome to TWiki! This is a TWikiSite (pronounced twee-kee site), a meeting place to work on common interests. Anyone can contribute using any web browser. TWiki looks like a normal Web site... except that it encourages contribution and editing of pages, questions, answers, comments and updates.
Mission: "TWiki is a leading-edge, web-based collaboration platform targeting the corporate intranet world. TWiki fosters information flow within an organization; lets distributed teams work together seamlessly and productively; and eliminates the one-webmaster syndrome of outdated intranet content."
"Wiki" systems are fundamentally editable web pages. It's a fun and useful way of communicating asynchronously over the web for many existing intranet and public Internet sites. TWiki is simple to learn and use. It aims to provide a transparent way for you to publish and exchange your ideas with others over the web.
How TWiki Works
Browse This is a site like other sites. Read and follow interesting links.
web: A TWikiSite is divided into webs, each one represents an area for collaboration. Your site has the following webs: | caad chair | ws 0506? | Übungen? | user list | Sandbox
topic: Each web is made up of hyperlinked topics (TWikiTopics) that appear in your browser.
WebChanges: in each TWiki web to find what's new
Write Speak your mind! From your browser you can change or add to anything you see in a TWiki topic. Use regular text, HTML or TWikiShorthand. To contribute:
Create An Account To be able to edit or write new content, you'll need to create an account for yourself. It's simple, and only takes a minute. TWikiRegistration This will also create your personal home page.
click Edit at the bottom of any topic and make your changes
click [ Preview Changes ] at the bottom to verify the topic (use your brower's Back button if necessary)
click [ Save Changes ]
Don't worry! It can be scary at first to change "public" content. Please just try it. Revision control keeps all content, nothing is lost. For special cases, access control is available yet you may find you don't need it in most cases. You'll soon see how successful WikiCulture works in this kind of collaboration environment. This is new. Just try to relax.
Experiment Edit your personal page or visit the Sandbox web.
Link To link to another topic, start by editing an existing topic.
To create a link to an existing topic type its JoinCapitalizedWords name. WikiWords (two or more capitalized words run together) link automatically.
To create a link to a new topic, enter a newly UsedPhrase.
When previewing, the links show and "?" (question marks) are used to create topics.
Another way to create a topic is to type it's WikiWord in the Go box or URL.
Topic history click Diffs at the bottom of a topic
Attach files click Attach to upload and attach any type of file.
Organize: You can learn to use TWikiForms and FormattedSearches to include topic information - for example, classify pages by subject, status, or date.
Learn moreTWikiTutorial is a 20-minute tour of TWiki essentials. WikiReferences links to selected articles and books about Wiki technology and online collaboration.
...discover TWiki details, and how to start your own site.
You can use color coding by web for identification and reference. This table is updated automatically based on WebPreferences settings of the individual webs. Contact caad-yearly@hbt.arch.ethz.ch if you need a separate collaboration web for your team.
A set of pages of information that are open and free for anyone to edit as they wish. They are stored in a server and managed using some software. The system creates cross-reference hyperlinks between pages automatically. See WelcomeGuest and TWikiSite for more information.
Back to:TWikiFAQ
-- PeterThoeny - 27 Nov 2000
Everybody can edit any page, this is scary. Doesn't that lead to chaos?
Answer:
TWiki is one of many WikiWikiClones, the first one was built by Ward Cunningham. Collaborating the Wiki way is different from other collaboration tools like Usenet. A distinct Wiki culture forms around these tools:
Any and all information can be deleted by anyone. Wiki pages represent nothing but discussion and consensus because it's much easier to delete flames, spam and trivia than to indulge them. What remains is naturally meaningful.
Anyone can play. This sounds like a recipe for low signal - surely wiki gets hit by the unwashed masses as often as any other site. But to make any sort of impact on wiki you need to be able to generate content. So anyone can play, but only good players have any desire to keep playing.
Wiki is not WYSIWYG. Contra the dumbing down of programming, it's an intelligence test of sorts to be able to edit a wiki page. It's not rocket science, but it doesn't appeal to the TV-watchers. If it doesn't appeal, they don't participate, which leaves those of us who read and write to get on with rational discourse.
Wiki is far from real time. Folk have time to think, often days or weeks, before they follow up some wiki page. So what people write is well-considered.
Your name, usually your first and last name connected without a space.
For example, Tim Berners-Lee's WikiName is TimBernersLee.
Your name is also a potentially valid WikiWord when used within a topic, however the home pages of registered users on this site are stored in the Main TWiki web. Prepend Main. when you sign your username in a topic - write Main.guest to link to Main.guest, your personal topic page in the Main TWiki web. This will ensure that your personal topic page is linked to at it's location in the Main TWiki web. For convenience, your signature is also provided to you for copying and pasting when editing a topic.
Though rarely used in common practice, you can use the special %MAINWEB%variable to prepend to user names, for example, %MAINWEB%.guest.
Presentation: TWiki Collaboration Tool - A Mature and Full Featured Platform for building Web Based Groupware Applications; by Peter Thoeny; TWiki:Main/TWikiPlatformPresentation
Book: The Knowledge Management Toolkit: Practical Techniques for Building a Knowledge Management System; by Amrit Tiwana; Prentice Hall PTR; ISBN:0130128538
Book: The Knowing-Doing Gap: How Smart Companies Turn Knowledge into Action; by Jeffrey Pfeffer and Robert I. Sutton; Harvard Business School Pr; ISBN:1578511240
Extreme Programming
Book: Extreme Programming Examined; by Giancarlo Succi and Michele Marchesi; Addison-Wesley Pub Co; ISBN:0201710404
Book: Extreme Programming in Practice; by James W. Newkirk and Robert C. Martin; Addison-Wesley Pub Co; ISBN:0201709376
Book: Extreme Programming Explored; by William C. Wake and Bill Wake; Addison-Wesley Pub Co; ISBN:0201733978
If you can enter text, you're ready for TWiki. With a few simple, intuitive TextFormattingRules, you'll be able to use plain text to create well-styled postings, instantly. Here's a fast-track guide to shorthand basics...
Separate each paragraph with a blank line.
To display a word or phrase in bold type, put it in asterisks: *bold type*.
To display a word or phrase in italic, put it in underscores: _italic_.
To display a word or phrase in bold italic, put it in double underscores: __bold italic__.
To link to another Wiki topic, type the WikiWord for that topic. To link to a Wiki topic in another web, type the name of the web, and a dot, first: Sandbox.WebHome.
If you enter a WikiWord for a topic that doesn't exist, it'll appear highlighted, with question mark at the end, prompting you (or someone else) to start off the new topic by clicking the ? - NewTopic? (click the ?, but don't save, to preserve the example!).
When entering WikiName signatures - like, guest - include "Main." as a prefix, since all TWiki member pages are in the Main web: Main.YourName.
For an external link, type the full URL: http://twiki.org/.
To prevent a WikiWord from becoming a link, type <nop> first, <nop>NoLinkPlease.
To indent with a bullet, enter [space][space][space][asterisk][space].
Use multiples of 3 spaces to start nested bullets.
That's 3-6-9-...
Start items in a numbered list with [space][space][space][1][space].
The "1" (or any number) will be replaced by the correct number, in order.
To add a new paragraph without restarting list numbering, use the %BR% variable, like below: Text added (in new paragraph)
and list numbering continues.
Always start counting spaces for bullets and such from the beginning of a new line.
To include an image, type its URL. You also can Attach an image to the page and display it with text %ATTACHURL%/yourimagefilename.jpg .
To display a word or phrase in MONOSPACED TYPE, put it in equal signs: =like this=. Use ==two== for bold: bold mono.
Use <verbatim> to enclose code excerpts, filenames, and other unformatted text, with the opening and closing tags on their own separate lines:
<verbatim>
unformatted text!
</verbatim>
Three (or more) consecutive hyphens expand into a horizontal rule: ---
A WikiTopic is one unit of information in a T/Wiki web. It is more or less a universal term in the world of Wikis. Each WikiTopic is displayed as one Web page in your browser. While debate swirls in high circles of TWiki development as to whether a topic should simply be called a page, there is a good case for the distinction:
a WikiTopic has a distinct WikiWord title that defines it; a Web page doesn't
a topic's content is self-contained, doesn't spill over onto other topics; a Web page can continue a subject, book-like, across many pages
particularly in TWiki, a topic has an array of features that make it distinct - attachments, relationships to other topics, classification data, independent revision control, and so on; a Web page has none of that
For now, a topic is used by TWiki to generate a regular Web page.
-- MikeMannix? - 12 May 2002
A WikiWord consists of two or more words with initial capitals, run together.
When you type a WikiWord, you establish a hyperlink. It's as easy as that.
WikiWords are styled like this because:
It makes Wiki hyperlinks instantly recognizable
It leads to interesting Wiki topics
It avoids the need to fiddle with HTML tags
It avoids over-general topics because at least two words are required
Syntax of a WikiWord
Uppercase letter(s)
Lowercase letter(s)
Uppercase letter(s)
Optional lowercase or uppercase letter(s) or number(s)
Web: Name without the uppercase letter(s), lowercase letter(s), uppercase letter(s) sequence
T5Wiki: Name with number before the uppercase, lowercase, uppercase sequence
Md5sumsAfterBurning: Name with number before the uppercase, lowercase, uppercase sequence
Know-How: Name with dashes in between
Hints
Insert WikiWords wherever you can. Rich linking helps to make a Wiki successful.
Be specific. All topics in a web share one name space. For example, instead of FunctionalSpec write BreadSlicerFunctionalSpec because other projects might also have a functional spec topic.
To stop a WikiWord from being turned into a hyperlink, insert the text <nop> immediately before the WikiWord.
It is recommended to create topics with singular names. Plural WikiWords are automatically linked to the singular topic, i.e. the link WikiWords links to the topic WikiWord.
Sometimes you have to be creative to find a good WikiName. Examples:
To create a topic about the the Bread Slicer 1.2 product, use BreadSlicer1dot2 or BreadSlicer1pt2, but not BreadSlicer1.2.
To create a topic about year 2000, you could go for YearTwoK or YearTwoThousand, but not Year2K or Y2K or Y2000.
Turn acronyms into WikiWords, i.e. take FaqIndex for a "FAQ index" topic.
You can specify any link label by using double square brackets, e.g. write [[TWikiAccessControl][access control]] to get a link to TWikiAccessControl that looks like access control.
The topic is assumed to be in the current TWiki web. Prepending the name of a TWiki web and a period links to a topic in another web.
This cookbook is intended to get you up and running with TWiki on Windows quickly, with as few problems as possible. The 'cookbook' approach is simply to restrict the many choices that someone installing TWiki must make, so that a reasonably well-defined procedure can be followed - new users can simply follow the steps, while experts can use this as more of a guideline. Please read TWiki:Codev.WindowsModPerlInstallCookbook in case you use mod_perl.
There is a huge volume of existing material on TWiki about installing on Windows, and I'm indebted to the many contributors for this - the aim of this cookbook is to synthesise the many tips into a recipe that works.
NOTE: This cookbook is probably incomplete (e.g. it doesn't cover authentication setup), but it has now been successfully tried out by a few people - it is quite accurate and should get you started if you follow the instructions. Please consider it beta quality, and provide feedback in TWiki:Codev.WindowsInstallCookbookComments.
NOTE: You will get the best results from following this cookbook exactly, using the same directories etc - however, if you really do need to vary things, it should be fairly obvious what to do.
20 Jul 2002 - added flags to grep commands in TWiki.cfg
27 Jun 2002 - more updates to list of required Cygwin packages
20 Jun 2002 - added creation of c:/twiki directory
17 Jun 2002 - updates to list of required Cygwin packages
15 Jun 2002 - various notes on Cygwin installation and troubleshooting: use of 'Unix' as default text file type (i.e. for mounting c:/cygwin directories) is essential for binary attachment uploads to work properly
27 Apr 2002 - update to settings for egrep and fgrep on some Cygwin versions (fix from TWiki:Main.DavidLeBlanc)
18 Apr 2002 - updates on Apache installation, setting TZ variable, and creation of c:\temp, based on comments by TWiki:Main.MaryDeMarco
3 Apr 2002 - added pcre to list of Cygwin packages (required by grep), fixed bug in Apache config (Apache doesn't allow '#' comments on same line as config)
19 Mar 2002 - comment about Windows 98
18 Mar 2002 - fix for register script committed to TWiki:Codev.TWikiAlphaRelease - most users can ignore this for now, but the edits in step 5 will eventually go away
14 Mar 2002 - minor fix to section on Apache environment
13 Mar 2002 - added a link to another Windows text editor
4 Mar 2002 - changed status to beta, notes about using spaces in file names, pointer on TWiki authentication setup, overview of Cygwin permissions and security issues
3 Mar 2002 - minor update to include uname -a command to check Cygwin DLL version, and delete Apache config's PassEnv line
25 Feb 2002 - clarified changes required to register, fixed minor typo in Cygwin binary mode section, after beta testing by TWiki:Main.JerryWard (thanks!)
Scope
This document covers installation of the TWiki -1-Feb-2003 production release in the following environment - if you want to use a different environment, feel free to use this as a guideline only.
Windows-specific security holes fixed in this build (check latest version at http://httpd.apache.org, but don't use Apache 2.0 yet)
Unix tools
Cygwin 1.3.9
Simplest way to get a whole set of required tools
Perl
Cygwin perl-5.6.1-2
Comes with Cygwin
RCS
Cygwin rcs-5.7-2
Comes with Cygwin, includes a file corruption bugfix
Why this choice of packages? Because I've tried them, and they work well, without requiring a complicated setup... In particular, Apache is the commonest choice for TWiki on Unix/Linux, Cygwin Perl is very close to Unix Perl, and the Cygwin RCS is regularly updated, with a recent TWiki-relevant bug fix in Feb 2002. Cygwin also lets you install the Unix tools, Perl and RCS in a single step, saving quite a lot of time.
More recent minor versions should be OK, but they can introduce bugs.
Major version upgrades, such as Apache 2.0 and Perl 5.8, are very likely to cause problems - for example, Apache 2.0 is unable to authenticate (see TWiki:Support.FailedAuthenticationWithApache2OnWinNT) users created by the current TWiki user registration script (due to a feature being removed in 2.0), and Perl 5.8 may introduce issues due to its Unicode features. Even though the Apache group says that Apache 2.0 is the best version, that's not true for TWiki.
Alternatives
There are doubtless other combinations of components that may work - in particular:
Using a different web server is certainly possible, but the setup required for each webserver varies greatly (see TWiki:Codev.TWikiOnWindows for pages about specific web servers). You may find it easiest to get a working system with Apache and then switch over to another web server.
Covering the whole range of additional possibilities, particularly web servers, would make this cookbook too complex, and is best handled as a separate activity.
Checking versions
If you already have some of these add-ons installed, here's how to check the versions - this assumes you have TWiki:Codev.CygWin already installed:
$ : Cygwin DLL version is the number in 1.3.x format
$ uname -r
$ less c:/your-apache-dir/Announcement
$ perl -v
$ rcs -V
If you have an older version of any component, do yourself a favour and upgrade it as part of the install process.
Pre-requisites and upgrades
You will need to have local administrator rights and to be comfortable with Windows administration.
This cookbook is intended for a clean install, i.e. none of these components are already installed. However, since Cygwin and Apache's installation process is fairly upgrade-friendly, upgrades should work as well - take backups of all your data and config files first, though!
Text editing
Editing Cygwin files is best done with an editor that can handle Unix file format (see the Cygwin binary mode section below) - the installation process includes nano, a non-GUI editor, but if you prefer to use a GUI editor, you should first install PFE, a freeware editor that supports Unix format files. PFE is available on download.com and Simtel.
Another good TWiki:Codev.OpenSource editor is SciTE (aka WSciTE), available at http://www.scintilla.org/SciTE.html.
The Unix/Windows Environment
It's a little known fact that you can use pathnames such as c:/apache almost everywhere in Windows - try it in a File Open dialogue box. The main exception is the Win2000 cmd.exe command line shell - here, you must use double quotes around forward slashes, e.g. dir "c:/apache" will work fine.
The reason this matters is that '\' is a special character to Perl and other tools, so it's much easier to use '/' everywhere.
The Cygwin environment
TWiki:Codev.CygWin is a Unix-like environment for Windows - many of its tools support the c:/apache format, but it also provides a more Unixlike syntax, e.g. /usr/bin/rcs.exe, because some Unix tools ported onto Cygwin only support the Unix format.
When you launch a Cygwin shell, your existing PATH variable is translated from the Windows format to the Unix format, and the ';' separators in the Windows PATH are changed into ':' separators as required by Unix. A Cygwin tool (e.g. Cygwin Perl or Cygwin RCS) will always use the Unix PATH format, and will accept Unix format pathnames.
The Apache environment
Apache runs as a native Windows process and has nothing to do with Cygwin (at least the version used in this cookbook doesn't). Hence it supports c:/ pathnames in its config files and the first line of Perl CGI scripts.
If you need to use spaces in file names (not recommended), put double quotes around the file name in the httpd.conf file. There have been some security-related bugs in Apache with long pathnames, which are a bit more likely if you use spaces, so it's best to just avoid long names and using spaces.
The Perl environment
Once Perl has been launched by Apache, it is in Cygwin mode, and so is everything it launches, including ls, egrep, and RCS tools that it (typically) launches with the bash shell.
If you need to use spaces in file names (not recommended), you may be able to put double quotes around the file name in the TWiki.cfg file - however, it's not clear whether all the TWiki code would work with this.
Installing Components
Enough background, let's get on with the installation.
TWiki (part 1)
Head to http://twiki.org, click the download link, and fill in the form to request a URL for download. You'll get an automated email, which should arrive by the time you need it.
The file to download is apache_1.3.X-win32-x86-no_src.msi where 'X' is 20 or higher
Note that this is a Microsoft Installer format file (.MSI) - this is supported by Windows 2000.
NOTE: If you are using Windows NT, download the .MSI installer (instmsi.exe) from the Apache Win32 download page - this enables you to install .MSI files. You may need to update the .MSI Installer if you have an old version under NT.
NOTE: The Apache package itself requires a download of around 2 MB, and up to 10 MB of free disk space once installed.
2. Install Apache
Double-click the .MSI file to run the installer
Specify c:\ as the installation directory - this actually installs Apache into c:\apache (if you specify c:\apache, it installs into c:\apache\Apache). Putting Apache into c:\Program Files is not recommended for easy editing of Apache config files from Cygwin.
You can choose to run Apache as a Win2000 service or as a normal program - see the Apache docs for details.
If necessary, start apache, either as a Win2000 service (using Admin Tools | Computer Management, or by typing apache -k start -n apache) or standalone (by typing apache -k start)
Congratulations, you now have a working web server!
To restart Apache after changing its config, type:
apache -k restart for standalone Apache process running in another window
apache -k restart -n apache for Apache running as a Win2000 service (-n gives name of service)
Another useful command is apache -k stop.
Cygwin, Unix tools, Perl and RCS
4. Install Cygwin
Head to http://cygwin.com, and click the Install Cygwin Now link. Save the setup.exe in a directory, e.g. c:\download\cygwin-dist.
Now run the Cygwin setup.exe file - this will also install Perl and RCS in one fell swoop.
Choose Internet install
On first page, accept the defaults (be sure that the default text file type is Unix to avoid problems with attachment uploads, and specify 'install for all users')
Select c:\download\cygwin-dist as the local package directory, and suitable proxy settings, then pick a local mirror site
In the package list screen, hit the View button until you get an alphabetical list that says Full to the right of the button.
Leave the radio button on Curr (Current)
The Current column shows what's installed on your system (if anything)
For each package, make sure the New column in the installer has a version number under it. If it says 'Skip' or 'Keep' (meaning it's already installed), single-click that word until a version number is shown. Make sure you select the following packages:
NOTE: Do not include lynx if you are upgrading from an older Cygwin installation (to avoid annoying DLL messages) - if you want Lynx, read the Cygwin FAQ entry and upgrade libncurses5.
Hit Next to do the installation.
NOTE: The mandatory packages require a download of about 12 MB - about half of this is Perl, which would be necessary even without Cygwin, and most of the rest is gcc, which is required for simple installation of Perl modules that use the C language. Something like 20 to 30 MB of free disk space should be enough for Cygwin, but I didn't test this (try a du -k / after a new install and let me know the last figure).
NOTE: The installer keeps a local copy of downloaded files, so it's easy to re-install without re-downloading.
Let the installer create the shortcuts suggested
5. Test Cygwin
Launch the desktop icon - this runs the bash shell, which has command line editing features
Use the cursor up key to recall previous commands - normal PC editing keys can then be used to edit a command
TIP: When typing a directory or file name, hit the TAB key after the first few letters of the name - bash will 'complete' the name. If bash beeps at you, hit TAB again to see the files/directories that match the name so far, and type a bit more before hitting TAB. This saves a lot of time!
Type rcs -V - you should see the RCS version, 5.7
Type perl -v - you should see cygwin mentioned in the first line, and the Perl version, 5.6.1
Type grep home /etc/passwd - you should see some output.
The Cygwin User Guide is well worth reading for some background on how Cygwin works.
6. Configure Cygwin for binary mode
This is very important - omitting this step leads to a partially working system that corrupts RCS files - without this, Cygwin tools (including Perl and RCS) will add unwanted carriage returns (Ctrl/M, '\r') to files in an attempt to translate between the Windows and Unix text file formats (Unix text files only use line feeds ('\n').
Stay in the Cygwin (bash) shell, and type the following (use only forward slashes, i.e. '/'):
$ mkdir /twiki /c c:/twiki
$ mount -b -s c:/twiki /twiki
$ mount -b -s c:/ /c
$ mount -b -c /cygdrive
$ mount
Device Directory Type Flags
C:\cygwin\bin /usr/bin system binmode
C:\cygwin\lib /usr/lib system binmode
C:\cygwin / system binmode
c:\twiki /twiki system binmode
c: /c system binmode
This configures /twiki (known as a 'mount point') to map onto c:/twiki and for that directory tree to always be in binary mode, and does the same for /c, mapping it onto c:/. The last-but-one command sets binary as the default for any unmounted drives (e.g. z:/, aka /cygdrive/z).
It is very important that all lines in the output of mount say 'binmode' under Flags
If the lines for C:\cygwin directories do not, you should uninstall and then re-install Cygwin to ensure that binary attachment uploads will work.
You can now refer to files using Unix paths, e.g. /twiki/bin/view or /c/apache/Announcement - see the Cygwin documentation for more details on this.
Now test this, still using the Cygwin shell:
Type cd /twiki
Type echo hi >t
Type cat -v t - you should see hi as the output
If you see filename errors, your mounts did not work for some reason - check your typing
If you see hi^M as output, your /twiki directory is not in binary mode
Clean up by doing rm t
This setup is written to the Windows registry, so there's no need to put these commands into a .profile file. For more information on binary vs text mode, see this User Guide section and this FAQ entry.
TWiki (part 2)
7. Download TWiki
Download the latest TWiki release from the URL that PeterThoeny sent you, and save it in the c:/twiki directory.
8. Install TWiki
Unzip the ZIP file under c:/twiki using WinZip, or by going into Cygwin and doing the following - you can hit the TAB key to complete filenames after you've typed the first part:
$ cd /twiki
$ unzip TWiki20011201.zip
Configuring components
Now that all the components are installed, you need to configure them.
Configuring Apache
The setup given here is fairly simple, in that it allows only TWiki to be served by the web server. For more complex setups, you can investigate the Alias and ScriptAlias commands that are left commented out in this configuration.
NOTE: This needs reviewing for security holes and to ensure nothing is missed, though this config does work.
1. Configure Apache (part 1)
Using a suitable text editor (e.g. Cygwin's 'nano', or the Windows PFE editor, unless you already know 'vi'), edit c:/apache/conf/httpd.conf as follows - this tells Apache where TWiki lives, and removes the need to tinker with the Windows 2000 environment settings.
If you are using nano, always launch it with nano -w filename - this turns off wrapping of long lines.
Note the trailing '/' characters in various places - they are important!
Create the c:\temp directory, by typing mkdir c:\temp in a DOS command line window
Edit the following lines, some of which already exist in the file:
# Change this to point to the Apache administrator (e.g. you)
ServerAdmin you@yourdomain.com
# Replaces DocumentRoot "C:/apache/htdocs"
DocumentRoot "C:/twiki"
# Replaces <Directory "C:/apache/htdocs">
<Directory "C:/twiki">
Add the following lines - the Alias and ScriptAlias lines can be omitted in this setup
# Alias /twiki/ "C:/twiki/"
# ScriptAlias /twiki/bin/ "C:/twiki/bin/"
<Directory "C:/twiki/bin/">
# RD: Changed None to All in next line, to enable .htaccess
AllowOverride All
Allow From All
Options ExecCGI
SetHandler cgi-script
</Directory>
# Environment setup required to run Apache as service or as a
# standalone process.
<IfModule mod_env.c>
# Adjust TZ for your server timezone, e.g. EST5EDT - put the non-daylight-savings
# timezone code first (e.g. EST or GMT), followed by the number of hours that it's behind GMT
# during non-daylight-savings time (use '-5' for timezones in advance of GMT).
SetEnv TZ GMT0BST
SetEnv RCSINIT -x,v/
# Adjust TEMP and TMP for your server and create directories if necessary
SetEnv TEMP c:/temp
SetEnv TMP c:/temp
SetEnv LOGNAME system
SetEnv HOME c:/twiki
</IfModule>
2. Configure Apache (part 2)
Add an AddHandler line to the <IfModule mod_mime.c> section of httpd.conf - this removes the need to rename all the TWiki CGI scripts later in the installation.
3. Configure TWiki
Edit the TWiki config file, c:/twiki/lib/TWiki.cfg (or in Cygwin terms, /twiki/lib/TWiki.cfg) as follows:
NOTE: It should be possible to use c:/twiki format pathnames for Cygwin, given the above binmode setup, but I have not tested this fully - a Cygwin Perl test script does generate binary mode files in this configuration, so it should work with RCS as well (really need a small RCS file corruption test case). Watch out for RCS file corruption carefully if you do try c:/twiki pathnames with Cygwin, and do report your experiences...
NOTE: Some recent versions of Cygwin (e.g. 1.3.10) seem to create 'symbolic links' from fgrep and egrep to grep, requiring the settings for these commands to point directly to grep (with suitable flags to provide fgrep and egrep behaviour).
# variables that need to be changed when installing on a new server:
# ==================================================================
# http://your.domain.com/twiki : link of TWiki icon in upper left corner :
$wikiHomeUrl = "http://yourdomain.com/bin/view";
# Host of TWiki URL : (Example "http://myhost.com:123")
$defaultUrlHost = "http://yourdomain.com";
# /caadtwiki/bin : cgi-bin path of TWiki URL:
$scriptUrlPath = "/bin";
# /caadtwiki/pub : Public data path of TWiki URL (root of attachments) :
$pubUrlPath = "/pub";
# NOTE: Next three settings should be valid absolute pathnames using Cygwin; if using
# TWiki:Codev.ActiveState Perl, use z:/twiki format pathnames if your TWiki directory is not on C:.
# Public data directory, must match $pubUrlPath :
$pubDir = "/twiki/pub";
# Template directory :
$templateDir = "/twiki/templates";
# Data (topic files) root directory :
$dataDir = "/twiki/data";
....
# Set ENV{'PATH'} explicitly for taint checks ( #!perl -T option ) :
# (Note: PATH environment variable is not changed if set to "")
# On Windows, $safeEnvPath needs only one component, the directory where RCS is installed
# - used by 'rcsdiff' to run 'co' program, so PATH must be correct.
# Unix/Linux setting:
# $safeEnvPath = "/bin:/usr/bin";
# Using Cygwin perl, so can use Unix-like paths, with ':' as separator.
# Note that /usr/bin and /bin are identical due to default /usr/bin mount
# in Cygwin. Must NOT use 'c:/foo' type paths, as ':' is taken as separator
# meaning that 'c' is interpreted as a pathname, giving Perl taint error.
$safeEnvPath = "/bin";
# If using ActiveState perl, use Windows paths instead
# $safeEnvPath = "c:/cygwin/bin";
...
# RCS directory (find out by 'which rcs') :
$rcsDir = "c:/cygwin/bin";
...
# Unix egrep command :
$egrepCmd = "/bin/grep -E";
# Unix fgrep command :
$fgrepCmd = "/bin/grep -F";
For the cookbook install using Cygwin Perl, there's no more TWiki.cfg editing to be done, so you can get onto the next section.
For TWiki:Codev.ActiveState Perl, you need to make these additional edits further down the file - this is the only place where backslashes are needed. (See TWiki:Codev.CookbookActivePerlSetup for some extra Perl setup that should remove the need for these edits.)
# NOTE: When using ActiveState Perl, you must specify
# a full Windows-style pathname, using '\\' for backslashes,
# for the ls, egrep and fgrep commands, because Cygwin's shell
# is not used - forward slashes are OK in Windows everywhere
# except in the cmd.exe shell. Drive letters are OK - e.g.
# 'c:\\foo\\ls' will work. When using Cygwin perl, just
# use the default '/bin/ls' type settings.
#
# Unix ls command :
$lsCmd = "c:\\cygwin\\bin\\ls";
# Unix egrep command :
$egrepCmd = "c:\\cygwin\\bin\\grep";
# Unix fgrep command :
$fgrepCmd = "c:\\cygwin\\bin\\grep";
Editing the CGI scripts
4. Editing the Shebang lines
Now to edit the curiously named 'shebang lines' at the top of the TWiki CGI scripts...
You must use the Cygwin shell to do this (unless you are a Perl expert) - don't use the Windows command shell, cmd.exe (aka DOS Prompt)
Then do the following, which quickly edits the 19 or so files, using Perl - the important lines are in bold.
Type the Perl line very carefully
If you do mis-type the perl line, you can restore from the .backup directory and re-run the command, as it will only edit the original files, not the backups with '~' suffixes.
If for some reason the edit goes wrong, just type cp .backup/* . (while within the bin directory) to restore the original distribution files. Use ls -a to see the .backup directory, and ls -a .backup to view its contents.
Optional step: you can do 'rm *~' to clean out the backups made by Perl, but that's not essential as all the original files cannot be executed. If you do this, type the command very carefully, as a space after the '*' will wipe out all files in this directory!
5. Minor changes to TWiki scripts
As an interlude, you now need to make some minor edits to files in the c:/twiki/bin directory, using a suitable editor (remember to use nano -w filename if you prefer nano to vi - or just use the Windows PFE editor).
Edit the register script in /twiki/bin - change line 200 to read as follows (insert the MIME::Base64:: part):
6. Installing required Perl modules
Some additional Perl modules are needed for the register script to work properly. Fortunately, there is an automated tool that makes it easy to do this - it's called cpan, and goes to the Perl module archive site, http://www.cpan.org/, to download all required modules, and then build and install them. Here's what you need to do:
First of all, you need to get the cpan tool configured and working - this is only necessary once. From the Cygwin shell, type the following (putting the export command in ~/.profile is recommended to make this setting persistent). Without the TEMP variable, some modules may fail to install on Windows 2000 and higher.
$ export TEMP=/c/temp
$ cpanLots of questions about configuration and preferences - just hit Enter until you
get to the questions about mirror sites, but answer the questions about FTP proxies etc
if you are behind a proxy-based firewall. The CPAN tool will fetch a series of files,
some quite large, as part of this setup process, so be patient...
NOTE: If you are behind a non-proxy-based firewall that requires the use of passive FTP, the initial downloads of files using Net::FTP may appear to hang - just wait 5 or more minutes, however, and the CPAN tool should eventually hit on ncftpget, which is part of Cygwin and does work OK. If this doesn't work and you are behind a typical NAT-based firewall, try doing the following at the Cygwin shell before running cpan - this forces Net::FTP to use passive FTP, letting it get through such firewalls:
$ export FTP_PASSIVE=1
If this works, add this line to your ~/.profile file for future use.
Once some initial files are downloaded, you are asked to select your continent and country, and then mirror sites - just type the number of the mirror sites you want to use (pick a few in case one is down):
...
(28) Turkey
(29) Ukraine
(30) United Kingdom
Select your country (or several nearby countries) [] 30
(1) ftp://cpan.teleglobe.net/pub/CPAN
(2) ftp://ftp.clockerz.net/pub/CPAN/
(3) ftp://ftp.demon.co.uk/pub/CPAN/
(4) ftp://ftp.flirble.org/pub/languages/perl/CPAN/
(5) ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
(6) ftp://ftp.plig.org/pub/CPAN/
(7) ftp://mirror.uklinux.net/pub/CPAN/
(8) ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
(9) ftp://usit.shef.ac.uk/pub/packages/CPAN/
Select as many URLs as you like,
put them on one line, separated by blanks [] 4 7 8
Enter another URL or RETURN to quit: []
New set of picks:
ftp://ftp.flirble.org/pub/languages/perl/CPAN/
ftp://mirror.uklinux.net/pub/CPAN/
ftp://sunsite.doc.ic.ac.uk/packages/CPAN/
Eventually, you'll get to the CPAN tool's shell prompt, where you need to install a few modules - the tool will do all the work for you.
NOTE: You will need to have previously installed the Cygwin make and gcc packages, which are required by the CPAN installer (gcc is required for modules that include C language code) - you can install them now by launching Cygwin's setup.exe from c:/download/cygwin-dist (no need to exit the CPAN installer).
cpan shell -- CPAN exploration and modules installation (v1.59_54)
cpan> install Net::SMTPMay already be installed - if it is, try 'force install', since it's useful to be able to set
firewall and passive FTP configuration when using Net::FTP. Make sure you answer 'Y' to the question
about whether you want to configure this package.
cpan> install Digest::SHA1Lots of output about how CPAN finds, builds and installs the module - watch for
any errors, though it should work fine if you have installed the Cygwin packages listed above (particularly 'gcc' and 'make').
cpan> install MIME::Base64May already be installed.
Re-locking RCS files
7. Re-locking files
First, some testing: in your browser, go to http://yourdomain.com/bin/testenv - this provides a lot of detail, including warnings. Write down the Apache server's userid that is given by this script - typically either 'system' or 'administrator' - I'll assume 'system' from now on.
If the testenv script doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt.
This 'system' user must own the locks on the RCS files, which are shipped with the lock held by 'nobody'. The reason this matters is that no revisions will be tracked by RCS unless the Apache userid matches that of the RCS file locks.
You can re-lock files using rcs -u and rcs -l, but it's a painfully manual process. Instead, just use Perl again to mass-edit all the RCS files, as follows:
NOTE: The 'NR <= 10' part of the Perl command ensures that it only operates on the first 10 lines, to avoid editing the body of RCS files for topics that happen to include the text 'nobody:' (like this one...)
$ cd /twiki/data
$ : Make a backup of all files
$ tar czvf all-files.tar.gz */*
$ : Test edit a single file to check your typing
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' Main/WebIndex.txt,v
$ diff Main/WebIndex.txt,v Main/WebIndex.txt,v~~~
5c5
< system:1.2; strict;
---
> nobody:1.2; strict;
$ : Now edit all the RCS files at once - use cursor-up to recall previous command
$ perl -pi~~~ -e 'NR <= 10 && s/nobody:/system:/ ' */*,v
$ : Check for any remaining files not edited
$ grep 'strict;$' */*,v | grep -v system
$ : Clean up - type this very carefully
$ rm */*~~~
If something goes wrong: to restore your existing files from the backup, just type tar xzvf all-files.tar.gz and all your files, both .txt and .txt,v, will be back as they were before the edits.
You have now re-locked all the RCS files and are almost ready to start using TWiki!
Email setup
8. Email setup for notification and registration
You need to set the SMTPMAILHOST to an SMTP email host that is reachable and currently working. Otherwise you'll get a confusing message from TWiki when registering new users or running mailnotify (for WebNotify), along the lines of:
Software Error: Can't call method "mail" on an undefined value at ../lib/TWiki/Net.pm line 187.
There are other settings to be made in TWikiPreferences, e.g. the WIKIWEBMASTER and (probably) the SMTPSENDERHOST (normally your mail server or TWiki server). See the TWikiInstallationGuide for more details, what's listed here is just enough to let you run the basic tests.
Testing your TWiki installation
It is important to test your TWiki installation before you release it to other users or put any significant data into it.
Here are the main things to test:
testenv - use http://yourdomain.com/bin/testenv and check for warnings
Page viewing (view script) - click around a few pages and make sure the links are OK
RCS diffs (rdiff script) - click on the Diffs link and on the '>' links at bottom of page
Edit a page, and register as a new user - tests page creation, use of register script to create a new user entry in /twiki/data/.htpasswd (the Apache password file), ability to send email via Net::SMTP, and whether SMTPMAILHOST was set correctly in TWikiPreferences.
If you get a failure to register or send email, check the Apache error log, and that all CPAN modules were installed correctly in Step 6, Installing required Perl modules.
Try typing tail -30 /c/apache/logs/error_log to see last 30 errors from Apache
Edit a page - check revision increased and set to current date/time
Edit the same page using another browser or PC, logging in as a different user - check there's a lock message (which you can override) and no double lines
Check the Apache error_log file to see if there are any RCS errors so far
Index - tests whether ls and grep are working
Search - more tests for whether ls and grep are working
Attachments - tests access to /twiki/pub directory.
Try a binary attachment upload and check the number of bytes in the file has not changed - if it has, see the Install Cygwin section's note on the default text file type.
Check the Apache error_log file again
Troubleshooting
If anything doesn't work, go back and check the configuration of the Apache httpd.conf file, and TWiki.cfg. Have a look at the Apache error log, c:/apache/logs/error_log, and the TWiki error log, /twiki/data/log*.txt, and if necessary enable debugging on selected scripts (the commands are right at the top of each script) - the results go into /twiki/data/debug.txt. There is also a /twiki/data/warning.txt file that contains less serious messages.
See TWiki:Codev.TWikiPatches in case there are patches (i.e. specific code changes) for particular problems that may affect you (e.g. TWiki:Codev.ChangePasswordOnWin2K).
If you find that the Index feature doesn't work, or topic name searches fail, you should check you have set $egrepCmd and $fgrepCmd correctly, as mentioned above.
By default, it only implements the Unix 'write' and 'execute' permissions bits - the former is controlled by the Windows Read-Only attribute, while the latter is automatically assigned to files named *.exe or *.com, and to files whose first line is a shebang (i.e. #!/bin/something). This is what has been used for this cookbook.
You can enable the 'ntea' or 'ntsec' models, which will increase security but are also likely to introduce permission problems.
I have not had any problems with TWiki permissions on Windows, unlike Linux/Unix, which is probably because I'm using the default security model for Cygwin. If you use the other models, you may still be OK if you have local admin rights, and Apache is running as the SYSTEM user (which it uses if started as a service). If you do have trouble in this area, see the TWikiInstallationGuide's advice, some of which will apply to TWiki:Codev.CygWin, and log any issues in TWiki:Codev.WindowsInstallCookbookComments.
Next Steps
See the TWikiInstallationGuide for other setup. In particular, you'll probably want to refer to the section on basic authentication - remember to use c:/twiki type filenames (i.e. Windows format) since you are using Apache for Windows.
See TWiki:Codev.WindowsModPerlInstallCookbook and TWiki:Codev.ModPerl for information on installing TWiki under Apache's mod_perl - this is somewhat more complex and follows a different model, so it's best to get some experience with TWiki, Apache and Perl first.
Format of filenames
In your TWiki on Windows installation, it's worth remembering that:
Apache configuration files (e.g. the .htaccess file and c:/apache/conf/httpd.conf) always use Windows format paths, with forward slashes, e.g. c:/twiki
The same is true for the first line of the TWiki Perl scripts (since this line is interpreted by Apache), e.g. c:/cygwin/bin/perl
All other lines in the Perl scripts use Unix format paths, e.g. /twiki (using Cygwin Perl as per this cookbook)
If you are using TWiki:Codev.ActivePerl, that will use Windows format paths, e.g. c:/twiki
Depending on the Perl version used (Cygwin or TWiki:Codev.ActivePerl), the TWiki.cfg file uses a mixture of Unix and Cygwin format paths - stick to the format used in the installation step for TWiki.cfg
RCS always uses Unix format paths, e.g. /twiki
Credits
Material in this cookbook is heavily based on the enormous number of contributions in TWiki:Codev.TWikiOnWindowsArchive and related topics - too many people to thank, but have a look at the contributor list to TWiki:Codev.TWikiOnWindowsArchive to get an idea!
People who've tested or reviewed this document and provided valuable feedback include:
You are currently in the TWiki web. The color code for this web is this background, so you know where you are.
If you are not familiar with the TWiki collaboration platform, please visit WelcomeGuest first.
The description above briefly explains how a background color corresponds to a particular web. It is included within other topics using the following directive:
%INCLUDE{"%TWIKIWEB%.YouAreHere"}%
On an ISP installation... The user and group - 
The 
.
It's not recommended to upload files greater than a few hundred K through a browser. Large files can be extremely slow-loading, and often time out. Use FTP for large file uploads.
, an image.
Sample.txt
Smile.gif
We recommend implementing at least some of these enhancements right after installation, to get a taste for what is possible. Some of these tips and enhancements should be implemented before or during initial roll-out.
This may spark your imagination to really customize your site so that it's optimal for your users. Slightly more advanced customization tips are listed in TWikiAdminCookBook.
Refactor / Edit
Done
Updated
New
Moved to...
View topic
Edit topic
New topic
Search topic
Print topic
Attach file
Since wabi-sabi represents a comprehensive Japanese world view or aesthetic system, it is difficult to explain precisely in western terms. According to Leonard Koren, wabi-sabi is the most conspicuous and characteristic feature of what we think of as traditional Japanese beauty and it "occupies roughly the same position in the Japanese pantheon of aesthetic values as do the Greek ideals of beauty and perfection in the West."
Wabi-sabi is a beauty of things imperfect, impermanent, and incomplete. It is the beauty of things modest and humble. It is the beauty of things unconventional.
The concepts of wabi-sabi correlate with the concepts of Zen Buddhism, as the first Japanese involved with wabi-sabi were tea masters, priests, and monks who practiced Zen. Zen Buddhism originated in India, traveled to China in the 6th century, and was first introduced in Japan around the 12th century. Zen emphasizes "direct, intuitive insight into transcendental truth beyond all intellectual conception." At the core of wabi- sabi is the importance of transcending ways of looking and thinking about things/existence.